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Introduction 


This section explains TRSDOS-II on a technical level. It 
teaches you how to use TRSDOS-II system routines within your 
own z-80 assembly language programs. You also may find the 
information useful in programming with BASIC or other 
languages. 


Memory Requirements 


TRSDOS-II resides on your primary drive; it occupies only a 
small portion of memory at any one time. The supervisor 
program, input/output drivers, and other essentials are 
always in memory. Auxiliary code is loaded as needed into 
an "overlay area." 

Memory addresses 0-10239 (X'0000'-X'27FF') are reserved for 
TRSDOS-II. 

All TRSDOS-II utilities use memory in the range of X'2800' 
-X'2FFF'. 

The following utilities use all of user memory: FORMAT, 
BACKUP, FCOPY {SYS} and single-drive COPY. 

You must locate user programs above X'27FF'. You may want 
to locate them above X'2FFF', so you can use the utility 
overlays without losing your program. 

Memory Requirements of TRSDOS-II 


Decimal Hex 

Address Area Address 


0-10239 TRSDOS-II Resident Area 0000- 

27FF 

10240- Utility Overlay Area 2800- 

12287 2FFF 
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Decimal 

Address 


Area 


Hex 

Address 


12288- 

User Area 

3000- 

61439 


EFFF 

61440— 

TRSDOS-II Demand Resident Area 

F000— 

65535 


FFFF 
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Video Display 


The display has two modes of operation — scroll and 
graphics. Cursor motion and allowable input characters are 
different in the two modes. 


Graphics Mode 

In the graphics mode, the display can be thought of as an 80 
by 24 matrix, as illustrated below: 


0 .... 6 .... 12 ... 18 ... 24 ... 30 ... 36 ... 42 ... 48 ... 54 ... 60 ... 66 ... 72 ... 79 


0 
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13 
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16 

17 
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19 

20 
21 
22 
23 


Note: The display has two character sizes: 80 characters 

per line and 40 characters per line. The above illustration 
shows the 80 characters-per-line mode. 



DISPLAY POSITIONS, GRAPHICS MODE 
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Each time an acceptable character is received, it is 
displayed at the current cursor position, which is set upon 
entry to the graphics-mode routines. After the character is 
displayed, the cursor position is advanced, as follows: 

If the cursor is to the left of Column 79, it advances 
to the next column position on the same row. 

If the cursor is at Column 79, it wraps around to 
Column 0 on the next row. 

Cursor movement works the same way in all directions. For 
example, if the cursor is at Row 23, Column 40 , and 
TRSDOS-II receives the X'FF' (graphics-down) code, the 
cursor wraps around to Row 0 in the same column. 
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Scroll Mode 


In the scroll mode, the display can be thought of as a 
sequence of 1920 display positions, as illustrated below: 


LineO 
Line 1 
Line 2 
Line 3 
Line 4 
Line 5 
Line 6 
Line 7 
Line 8 
Line 9 
Line 10 
Line 11 
Line 12 
Line 13 
Line 14 
Line 15 
Line 16 
Line 17 
Line 18 
Line 19 
Line 20 
Line 21 
Line 22 
Line 23 


Note: The display has two character sizes: 80 characters 

per line and 40 characters per line. The illustration above 
shows the 80 characters-per-line mode. 

Each time an acceptable character is received, it is 
displayed at the current cursor position. Then, the cursor 
advances to the next higher numbered position. 

When the cursor is on the bottom line, and a line feed or 
carriage return is received, or the bottom line is filled, 
the entire display is "scrolled." TRSDOS-II: 


* 0,1, 2, 3, 4, 5,6. 

80,81,82,83. 

.78, 79 ' 

.158,159 








.*. 



1760,1761 . 

1840,1841 . 

t _ 

.> 

...1838,1839 
...1918,1919 


DISPLAY POSITIONS, SCROLL MODE 
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1. Deletes Line 0 

2. Moves Lines 1-23 up one line 

3. Blanks Line 23 

4. Sets the cursor at the beginning of Line 23 

Note: You can use the SCROLL SVC to protect Lines 

0 to 22 from scrolling. 
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Diskette Organization 


TRSDOS-II can use either single- or double-sided, 
double-density diskettes. It automatically formats each 
diskette according to its type. 

Each side of the double-sided diskette contains 77 tracks, 
numbered 0-76. Therefore, you can think of the double-sided 
diskette as one diskette with 154 tracks. 

The single-sided diskette has 77 tracks on one side only. 

The sector is the basic unit of space allocation in 
TRSDOS-II. Except for Track 0, each track contains 32 
sectors, numbered 1-32. Each sector contains 256 bytes. 

TRSDOS-II reserves Track 0 for itself and formats it 
single-density. Track 0 contains 26 sectors and 128 bytes 
per sector. On double-sided diskettes, only one side has a 
single-density Track 0. 


The capacity of a double-sided diskette is: 

(153 * 32 * 256) + (1 * 26 * 128) = 1,256,704 bytes 


The capacity of a single-sided diskette is: 

(76 * 32 * 256) + (1 * 26 * 128) = 625,920 bytes 


Single-sided 

Diskette Tracks Sectors Bytes 


1 


76 2,432 622,592 

1 32 8,192 

1 256 
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Double-sided 

Diskette 


Cylinders Tracks 


Sectors 


Bytes 


1 


77 

1 


153 

2 

1 


4,896 1,253,376 

64 16,384 

32 8,192 

1 256 
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Disk Files 


Methods of File Allocation 


TRSDOS-II gives you two ways to allocate disk space for 
files: dynamic allocation and pre-allocation. 


Dynamic Allocation 

With dynamic allocation, TRSDOS-II allocates sectors only 
when the file is written to. For example, the first time 
you open a file for output, no space is allocated. The 
first space allocation is done at the first write. 

TRSDOS-II allocates more space as required by later writes. 

With dynamically allocated files, TRSDOS-II de-allocates 
(recovers) unused sectors when you close the file. 


Pre-Allocation 

With pre-allocation, you specify the number of sectors to be 
allocated. The only way to do this is by using the CREATE 
command when you create the file. 

When the file becomes too large for the space allocated to 
it, TRSDOS-II dynamically extends (enlarges) it as needed. 

It does not, however, de-allocate unused sectors when you 
close a pre-allocated file. To reduce the size of a 
pre-allocated file you must copy it to a dynamically 
allocated file. The COPY command does this automatically 
when the destination is a dynamically allocated file. 


Record Length 

TRSDOS-II transfers data to or from a diskette one sector 
(256 bytes) at a time. These data blocks are called 
"physical records." 

TRSDOS-II transfers data to or from a file in buffers which 
are from 1 to 256 bytes long. These buffers are called 
"user records" or "logical records." 


Radio/haelf 


3/9 








TRSDOS-II 


REFERENCE MANUAL 


TRSDOS-II automatically "blocks" your logical records into 
physical records to be transferred to the disk. It also 
automatically "de-blocks" the physical records into logical 
records, which are used by your program. 

Therefore, your only concern during file access is with 
logical records. You never need to worry about physical 
records, sectors, tracks, and so on. This is to your 
benefit, since physical record lengths and features may 
change in later TRSDOS-II versions, while the concept of 
logical records will not. 

From this point on, the term "record" refers to a "logical 
record." 

Spanning 

If the record length is not an even divisor of 256, the 
records automatically are spanned across sectors. 

For example, if the record length is 200 , Sectors 1 and 2 
look like this: 
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Fixed-Length and Variable-Length Records 

TRSDOS-II files can have either fixed-length or 
variable-length records. Files with fixed-length records 
are called FLR files; files with variable-length records, 

VLR files. 

For an FLR file, you set the record length when you open the 
file for the first time. This length can be from 1-256 
bytes. You cannot change the set record length unless you 
overwrite the file with new data. 

For a VLR file, you specify the record length in a 1-byte 
length field at the start of each record. The lengths of 
records in a VLR file can vary. For example, the first 
record in a file might have a length of 32; the second 
record, 17; the third record, 250; and so on. 

The length byte for a variable-length record indicates the 
entire length of the record, including the length byte. It 
can be from 0-255. You can use 1, but it has no meaning 
because no record is 1-byte long. 


Examples 

A length byte of 0 indicates that the record has 255 bytes 
of data: 


Length 

Byte Data 
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A length byte of 2 indicates that the record has 1 byte of 
data: 


Length 

Byte 


2 


t 

one byte of data 


A length byte of 16 indicates that the record has 15 bytes 
of data: 


Length 

Byte Data 


Hi—H—1 
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Record Numbers 


Records are numbered from 0 (beginning of file) to 
16,777,214. 

A file may contain up to 16,777,216 bytes of storage. 
Therefore, to determine the number of records a file can 
hold, use the following formula: 


16,777,216 / logical record length = number of records 
For example: 

16,777,216 / 38 = 441,505 records. 

For a file with a record length of 1, the number of records 
cannot exceed 16,777,214. 

The record number 16777215 (X'FFFFFF') positions to the "end 
of file" (EOF), regardless of the actual number of records 
in the file. 

Record Processing Capabilities 


TRSDOS-II allows both direct and sequential file access. 

Direct access, sometimes called "random access," lets you 
process records in any order you specify. 

To get direct access to Records 0-65533, you simply specify 
the record number (when using one of the direct access 
SVCs). 


To get direct access to Records 65534-16777216, however, you 
must choose the extended file access mode when you open the 
file. This mode specifies the record number in three bytes, 
letting you use the large number. 

The direct access SVCs are DIRRD (direct-read) and DIRWR 
(direct-write). 


Sequential access lets you process records in the order in 
which they are stored in the file. TRSDOS-II automatically 
accesses the record that follows the last one processed. 
When you first open the file, it accesses Record 0. 
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FLR files can be opened by either direct access or 
sequential access. 

VLR files can be opened only by sequential access. You 
cannot position to a specific record, since the varying 
record lengths make it impossible to calculate the record's 
position. 

The sequential access SVCs are READNX (read-next) and WRITNX 
(write-next). When you first open the file, sequential 
processing starts with Record 0 . However, you can use DIRWR 
and DIRRD to position to the EOF. 


Examples with FLRs 

Assume you have an open FLR file. Here are some typical 
sequences you can do via the file processing routines: 

. Read and/or write records in the file — in any 
order. 

Using DIRRD and DIRWR, you can: read Record 5, 
write at the EOF, read Record 3, write Record 3, 
and so on. 

. Read or write sequentially, starting anywhere in 
the file. 

Do a DIRRD to the record at which you want to 
start. Then, do READNX or WRITNX until done. 

. Write sequentially, starting at EOF. 

Do a DIRWR to the EOF. Then, do WRITNX until 
done. 

. Learn the number of records in a file. 

Do a DIRRD to the EOF. Then, use the LOCATE 
routine to get the current record number. This 
equals the number of records + 1. 


Examples with VLRs 

Assume you have an open VLR file. Here are some typical 
sequences you can do via file processing routines: 
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Read or write sequentially, starting at the £irst 
record. 

Do READNX and WRITNX until done. 


Write sequentially, starting at the EOF. 

Do a DIRWR to the EOF. Then, do WRITNX until 
done. 


Note: Whenever you write to a VLR, the last record you 
write becomes the end of file (EOF), automatically. 


You cannot update a VLR file directly. You must read in the 
file and output the updated information to a new VLR file. 
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Supervisor Calls 


Supervisor calls (SVCs) are operating system routines 
available to any user program. They alter certain system 
functions and conditions; let you access files; do 
input/output to the keyboard, video display, and printer; 
and do various computations. 

The available TRSDOS-II SVCs are: 


KEYBOARD SVCs VIDEO SVCs 


KBCHAR 


CURSOR 

VDINIT 

KBINIT 


SCROLL 

VDLINE 

KBLINE 


VDCHAR 

VDREAD 

KBPUT 


VDGRAF 

VIDRAM 

VIDKEY 




PRINTER SVCs 

COMMUNICATIONS SVCs 

PCTRL 


ACTRL 

BCTRL 

PRCHAR 


ARCV 

BRCV 

PRINIT 


ATX 

BTX 

PRLINE 



RS232C 

SYSTEM 

CONTROL SVCs 

FILE ACCESS SVCs 

CLRXIT 

HLDKEY 

CLOSE 

LOCATE 

DATE 

INITIO 

DIRRD 

OPEN 

DELAY 

JP2DOS 

DIRSET 

RAMDIR 

DOSCMD 

RETCMD 

DIRWR 

RDDIR 

ERRMSG 

SETBRK 

DISKID 

READNX 

ERROR 

SETUSR 

FILPTR 

RENAME 


TIMER 

KILL 

REWIND 




WRITNX 

COMPUTATIONAL SVCs 

MISCELLANEOUS SVCs 

BINDEC 


LOOKUP 

SORT 

BINHEX 


PARSER 

STCMP 

MPYDIV 


RANDOM 

STSCAN 



SOUND 

WILD 

Note: 

Appendices C 

and D, the SVC quick 

reference 

summarize each SVCs 

function. 
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Each SVC has a function code that you use to call it. These 
codes range from 0 through 127. The first 96 codes (J0-95) 
are defined by TRSDOS-II. Codes 96-127 are available for 
you to define (see the SETUSR SVC). 


SVC Notation 

In this section we use the following notations: 
Notation Meaning 


RP = data 
nl < R < n2 

(RP) = data 

NZ = Error 


Register Pair RP contains the data 

The register pair contains a value greater 

than nl and less than n2 

Register Pair RP contains the address 

of ("points to") the data 

If the Z flag is not set, an error 

occurred 


When a range is not given in the description of the SVC, you 
can use any representable number. For example, a register 
can contain any value from J0-255. 


Calling Procedure 

All SVCs are executed via the RST 8 instruction. 

1. Load the function code of the desired SVC into 
Register A. Also load any other registers that 
the SVC needs. See "Supervisor Calls." 

2. Execute an RST 8 instruction. 

3. If the function is successful, the Z flag is set 
upon return from the SVC. If the Z flag is not 
set, there is an error. Register A has the 
appropriate error code (except after certain 
computational SVCs, which use Register A to 
return other information). 

During the execution of an SVC, the SVC processor does not 
alter any memory above X'2FFF'. Only those Z-80 registers 
used to pass parameters from the SVC are changed. However, 
all the prime registers are used by TRSDOS-II; they are not 
restored. 
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Examples 


Time-Delay 

LD 
LD 
RST 


BC,TIMCNT 
A, 6 
8 


LENGTH OF DELAY 
FUNCTION CODE 6 
JUMP TO SVC 


= DELAY-SVC 


DELAY OVER-PROGRAM CONTINUES HERE 


Output a Line to the Video Display 


HL, MSG 

B, 10 

C, 0DH 
A, 9 


LD 
LD 
LD 
LD 
RST 8 

JR NZ, GOTERR 


POINT TO THE MESSAGE 
B = CHARACTER COUNT 
C=CTRL CHAR. TO ADD AT END 
CODE 9 = DISPLAY LINE-SVC 
JUMP TO SVC 
JUMP IF I/O ERROR 


IF NO ERROR THEN PROGRAM CONTINUES HERE 


Get a Character from the Keyboard 


GETCHAR LD A, 4 


RST 8 

JR NZ,GETCHAR 
; CHARACTER IS IN REGISTER B 


CODE 4 = GET CHARACTER-SVC 
JUMP TO SVC 

DO AGAIN IF NO CHARACTER 


Using the Serial Communications SVCs 
Initialization 

Before doing any serial I/O, you must initialize the channel 
you want. Use either the SETCOM library command or the RS232C 
SVC. 


Input/Output 

All serial I/O is character-oriented, similar to keyboard 
input and video output. The main difference is that your 
program must check the communications status at various 
times. This is done to ensure that the communications link 
is in place and that data is not being lost. 
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After any attempted serial I/O, TRSDOS-II returns the 
communications status to your program in Z-80 Register A. 
The bits in the register are used individually to show the 
on/off status of various conditions. Certain bits apply to 
transmit operations; others apply to all serial I/O. 


Programming with TRSDOS-II 

This section tells you how to execute your own 
machine-language programs under TRSDOS-II. It has two 
sub-sections: 

. Program Entry Conditions — How control is 

transferred to your program after the program is 
loaded from the disk 

. Handling Programmed Interrupts — How to write an 
interrupt service routine for <BREAK> key 
processing and TIMER interrupts 

To create and use a program, follow this procedure: 

1. Enter the program into memory, using DEBUG, or via 
the serial interface channel from another device, 
or using an assembler and linker. 

2. If you use DEBUG or an I/O channel to load the 
program, use the DUMP command to save the program 
as an executable disk file, setting the load and 
transfer addresses. 

3. To run the program, input the filename to the 
TRSDOS-II command interpreter (TRSDOS-II Ready 
mode). 


Program Entry Conditions 

Upon entry to your program, TRSDOS-II sets up the following 
registers: 

BC = address of the first byte following your 

program (the first free byte for use by your 
program). 

DE = highest unprotected memory address (the end of 
memory that can be used by your program). 
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HL = address of the buffer containing the last 
command entered to the TRSDOS-II command 
interpreter. 

The first byte of the buffer contains the 
command line length, excluding the carriage 
return. The text of the command follows this 
length byte. For example: 



length 1st byte 2nd byte nth byte N 
of text of com- of com- of com- X’OD’ 
n mand mand mand 


Handling Programmed Interrupts 

TRSDOS-II allows two user-programmed interrupts as described 
under SETBRK and TIMER. When either kind of interrupt is 
received (you press the <BREAK> key or the TIMER counts to 
zero), control transfers to your interrupt handling routine. 

Note: System routines called by your program or called by 

interrupt handlers can be interrupted, also. 

Upon entry to your interrupt processing routine, TRSDOS-II 
sets up the registers as follows: 

(SP) = address of the next instruction to be 

executed when the interrupt was received. 

Other registers: 

Contents are the same as they were when the 
interrupt was processed. 

Before doing any processing, you should save all registers. 
When you finish processing, restore all registers and 
execute a return to continue with the interrupted program. 

Keep the interrupt handling routines short. Ideally, the 
routine simply flags the main program that an interrupt has 
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occurred, and then returns. The main program then can 
respond to the interrupt flag when convenient. 

Always end your interrupt handler with the RET instructions 
and with all registers intact. 

TRSDOS-II is serially reusable but not always re-entrant. 
Specifically, your interrupt routine should not call 
TRSDOS-II SVCs, since under some conditions this causes 
unpredictable results. 


Program Files 

This section describes the required format and structure of 
program files. In it you'll also find a summary of the 
procedure for writing a program file using TRSDOS-II 
file-access SVCs. 


Program File Format 

A program file is stored on the diskette in blocks, which 
might look like this: 



256 Bytes 


?56Bvtes 



The lengths of the blocks vary, depending on the type of 
block and the amount of information in it. The blocks must 
border each other. There can be no unused bytes between 
them. 

There are three major types of blocks: 


Program data blocks — These contain the actual 
program data, prefixed by four bytes of header 
information. 

Comment blocks — These contain documentation 
for the programmer. Comment blocks are not loaded 
or examined by the loader. Comment blocks are 
prefixed by two bytes of header information. 
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. Trailer blocks. Each program file ends with a 

trailer block. It marks the end of file (EOF) and 
tells TRSDOS-II what to do after the file has been 
loaded — either to transfer to a specified 
address or to return to the caller. Trailer 
blocks are four bytes long. 

The first byte in a block identifies the block type, as 
follows: 

Contents (Hex) Block Type 


01 

Program data 


05 

Comment block 


02 

Trailer block; 

jump after 


loading 


03 

Trailer block; 

return to 


the caller after loading 

00 , 04, 06 - FF Reserved for TRSDOS-II use; 

the loader fails if one of 
these codes is used 


Structure of Program Data Blocks 
Program data blocks consist of the following: 
Byte # Contents 


1 Block identifier (equals binary 1) 

2 Length (the number of bytes of program 
data plus two for the load address) 

3-4 Load address (where the following 

program data starts loading into RAM); 
it must be in the LSB-MSB format 
5-end Program data 

The length byte gives the number of bytes in the rest of the 
block — following the 2-byte load address. This sum may 
range from 3 (the 2-byte address plus 1 byte of data) to 258 
(the 2-byte address plus 256 bytes of data). You must 
translate the sum into the range J0-255. 
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To do this, take the number of program bytes and increment 
by two. Note that values greater than 255 "wrap around" to 
0, 1, and 2. Here is a table: 


Number of 

Bytes after Address Value for 

(program data only) Length Byte 


1 

2 

3 


3 

4 

5 


• • • 

253 

254 

255 

256 


255 


0 

1 

2 


The load address tells TRSDOS-II where in RAM to load the 
data in the block. TRSDOS-II loads the bytes serially. The 
load address must allow the entire block of program data to 
load in the "user" area of RAM. 


Structure of Comment Blocks 
Comment blocks consist of the following: 
Byte # Contents 


1 Block identifier (equals binary 5) 

2 Length (the number of bytes in the 
comment) 

3-end Comment 

The length byte gives the number of bytes in the comment 
(the number of bytes after the length itself). This sum 
ranges from 0—255 - 

Length Byte Comment Length 


0 0 

1 1 

2 2 

• • • • • • 

255 255 
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Structure of Trailer Blocks 

Each program file ends with a single trailer block that 
tells TRSDOS-II what to do next: 

Jump to a specified "transfer" address 
or 

Return to the caller 

Trailer blocks consist of the following: 

Byte # Contents 


1 Block identifier (equals binary "2" or "3") 

2 Length (equals 2) 

3-4 Transfer address; it must be in the LSB-MSB 

sequence and must be in the user area of RAM 

If the block identifier equals 2, TRSDOS-II jumps to the 
transfer address after loading the program. If it equals 3, 
TRSDOS-II does not jump to the transfer address. Instead, 
it returns to the caller after loading the program, with the 
following prime registers set: 

HL' = transfer address taken from the trailer block 

DE' = address of the last usable byte 

BC' = first byte following the program just loaded 


Procedure for Writing a Program File 

Program files must have fixed-length records of length 256 
and must have the P (program) access type. You set both 
of these when you create the file, using a creation code of 
1 or 2 (see the OPEN SVC). 

The TRSDOS-II program loader treats the program file as a 
serial byte stream, independent of the record boundaries. 
The loader assumes the program blocks are "back-to-back" 
(there are no unused bytes between blocks). As programmer, 
you are responsible for: 

1. Storing the correct byte sequence in the logical 
record area. 
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2. Calling the disk write SVC (DIRWR) when each 

256-byte record is filled. Blocks can and must 
"span" sectors. The only unused bytes in the file 
are after the trailer block. See the illustration 
below. 

TRSDOS-II does not load user program below "user RAM." You 
also should make sure blocks do not load above "user RAM." 

Note: The TRSDOS-II DUMP command always writes a 
comment as the first block in the file. The 
comment contains the filespec, followed by the 
current TRSDOS-II time/date text. 
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Illustrated Program File Listing 


ERRPRINT 


BYTE 1...5...10. 


. 15. 


. 20 . 


TYPE=F 

.25.-.30...35. 


.40. 


Tue Sep 16 1980 260 — 01.12.43 PAGE 1 

.45...50...55...60...65...70...75...80...85...90...95..100 


1 .♦ERRPRINTs 1WED0CT 31979276 0.22.41102. ..!...3>4.>4.0..>. 

02455554453354444523333333323233233333020E21E0333CC1E1F33CC1ECC040031CCC000E000000000000000000000000 
22029E4A1754F3403197927600E22E4110jl0081EF63E4FD4F08E4FD4F956FEDE3FIS 


Block ID 
05=Comment 

Length 
of Comment 



Jump 

Address 


Comment 


Length 


Program Data 


Length 


First Byte of Program Data 


TRSDOS' 

EF00 

si I DEBUG Program 

IE EF 06 33 3E 

34 

CF 

CD 

14 

EF 

10 

F8 

3E 

34 

CF 

!... 

3>4. 


EF10 

CD 

14 

EF 

C9 

C5 06 

4F 

0E 

0D 

3E 

13 

CF 

Cl 

C9 

00 

00 




EF20 

00 

00 

00 

00 

00 00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 




EF30 

00 

00 

00 

00 

00 00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 




EF40 

00 

00 

00 

00 

00 00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 




EF50 

00 

00 

00 

00 

00 00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 




EF60 

00 

00 

00 

00 

00 00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 




EF70 

00 

00 

00 

00 

00 00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 




PC 

SP SZHPNC 

AF 

BC 

DE 

HL 

IX 

IY 

AF’ 

BC’ 

DE’ 

HL’ 


EF00 

21FE 011100 

0054 EF1E EFFF 2700 

0000 0000 2144 

0260 

2701 

EF00 



? p 


Jump Address 
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High-Memory Modules: 


Their Addresses and Uses 


As mentioned earlier, there are five high-memory modules 
that are conditionally loaded. They are DO, SPOOL, HOST, 
DEBUG and the communications drivers. They reside in high 
memory (above X'F000 '). The approximate memory map is as 
follows: 


Module 


Address 


Comm drivers 

DEBUG 

HOST* 

SPOOL* 

DO* 


X' F000' 
X' F400’ 
X' F400 ' 
X' F64J3' 
X' FC8J0' 


* Cannot be used with DEBUG 


Addresses may change in future releases. 

If your application requires a large amount of RAM, you may 
need to use high memory. For example, you may have a large 
BASIC program or a machine-language subroutine that you must 
link to BASIC. In either case, you might need a full RAM 
for the BASIC program itself. You must use high memory. 

If you do use high memory, keep in mind the following: 

. If you use BASIC, the use of high memory gives you 
slightly less RAM for your program and variable 
storage than you had with TRSDOS. 

Upon program-load, TRSDOS-II gives X'EFFF' 
in Register DE as the high-memory address. 

If you must, you may override this limit by 
specifying this command line: 

BASIC - M: upper limit of hiqh-RAM address 

The address to use as the upper limit must never 
exceed decimal 63487. The same rule applies to an 
applications program. 


The use of high RAM prevents the use of certain 
high-memory modules. 
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Assume that you invoke a system function that 
loads high RAM with a module. Then, your 
application loads something on top of it. 
(TRSDOS-II cannot prevent you from overlaying an 
already loaded high-memory module.) You are going 
to have problems. (See the memory map above for 
details.) 

Be careful about overlaying the addresses of the following 
modules: 

. Communications drivers — If you use a serial 
printer, do not overlay X'FjBjEfjB'-X'FSFF'. 

The code in that area must be intact if your 
application has printed output. That is when the 
comm drivers are active. Overlaying in this area 
can cause serious problems. 

. SPOOL — This is another module that can be 

used by almost any application that has printed 
output. To give operator flexibility, you should 
not use the RAM area of X'F640*-X'F&00' in your 
application software. 

If you must use this RAM area, make it clear to 
the operator that he may not use SPOOL. If any 
of the spool code space is overlayed after 
TRSDOS-II has loaded the spool code in that area, 
serious problems will result. 

. HOST — Lets a remote terminal execute your 

applications and programs as if the remote were 
local (the local keyboard and video). Again, 
using this space limits the operator's flexibility 
and causes serious problems. 

You can use the high-memory space without causing 
problems, if you plan carefully. Know what you need and 
when you need it. Then, tell the operator what to do (or 
not to do) when running your application. 

For example, assume that your application program does not 
create printed output. In this case, you do not need the 
spool or comm drivers areas (if the comm drivers are needed 
just for serial printer support). 
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To use this space, make sure SPOOL and the comm drivers are 
not active before or during the run of the application. Do 
this by starting execution of the application with a DO file 
(which resides in the top of RAM). 

In this DO file, you may turn off SPOOL and the comm drivers 
before the application is executed. Remember that you must 
turn off both Serial Channels A & B for the high-memory comm 
drivers to be inactive. 

For full operational flexibility, you should stay away from 
the high-memory areas. Then, you can use all of the 
high-memory routines during program execution. 

Future releases of TRSDOS-II may provide more features or 
routines that will use high memory. Keep this in mind when 
you design your applications. To use these features, you 
may have to update your high-memory subroutines. Consider 
the efforts required to make these program changes. Your 
program may be hard to update, or it may be hard to get 
revised copies out to the users. 
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Function Code 100 
Performs control functions on Serial Channel A. 


ACTRL 

Control Channel A 


TRSDOS-II sets up ARCV, ATX, and ACTRL when you initialize 
Channel A with RS232C. If you call any of these routines 
while the channel is not initialized (active), you get an 
error return code of 1 (no function code exists). 

Entry Conditions 
A = 100 

B = option switch 

Exit Conditions 

NZ = Error 

B = status code 


The option switch settings are: 
option 

switch Result 


0 Gets the current status of the serial I/O 

(SIO) channel into Register B. 

1 Gets the current character count in the 
serial receive buffer into B. 

2 Turns on Request to Send (RTS). RTS is on 
when the channel is initialized. 

3 Turns off RTS. 

4* Starts transmitting the break sequence. 

5 Stops transmitting the break sequence. 

6 Resets the serial receive buffer count to 
zero. 

7 Resets the SIO error condition. 


* Before transmitting a break sequence, make sure the 
sure the transmit buffer is empty. As the programmer, 
you are responsible for sending the break sequence for 
the appropriate time period, as required by the 
application or host computer. 
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The 8-bit grouping of flags returned in Register B consists 
of: 


Bit Meaning 


0 Clear to Send (CTS) is not present 

1 Unused 

2 Transmitter is busy 

3 Modem data carrier is not present 

4 Parity error is occurring in the byte that is 
being received 

5 Data overflow is occurring because of a byte that 
is being received 

6 Framing error is occurring in the byte that is 
being received 

7 Break sequence (extended null character) is being 

received 


Radio /hack 


3/32 









TRSDOS-II 


REFERENCE MANUAL 


ARCV 

Channel A Receive 


Function Code 96 


Returns a single character from Serial Channel A. 

TRSDOS-II sets up ARCV, ATX, and ACTRL when you initialize 
Channel A with RS232C. If you call any of these SVCs while 
the channel is not initialized, you get an error return code 
of 1 (no function code exists). 


Input Buffer 

Each channel (A and B) has an internal receive buffer to 
reduce overruns when receiving data at high speeds. This 
buffer is a first-in, first-out buffer (FIFO) which is 
established when the channel is initialized. 

When a character is received, the character and the hardware 
status code are placed in the Channel A buffer. If Channel 
A has not been initialized, no characters are received. 

An overrun occurs when a character is received and there is 
no more room in the buffer. The character that caused the 
overrun replaces the last character received. Bit 5 of the 
hardware status code is set; this indicates that an overrun 
occurred. 

When the ARCV SVC is executed, the oldest character in the 
buffer is returned to Register B; the hardware status at the 
time the character was received is returned to Register A. 

Note: When a character that caused an error is 

returned to Register B, the error is indicated in 
Register A. 

If there are no characters "waiting" in the buffer, the 
communications status returned in Register A reflects the 
current status of the serial interface. 

Entry Conditions 
A =96 
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Exit Conditions 

A = status code 

B = character returned , if any 

NZ = Character was not received, check the status 

code 

C flag = Modem carrier was not present when you entered 
the SVC 

The 8-bit grouping of flags returned in Register A (after 
serial input) consists of: 

Bit Meaning 


0 Not used 

1 Not used 

2 Not used 

3 Modem carrier was not present 

4 Parity error occurred on the last character 
received in Register B 

5 Data is lost because of an overflow; Register B 
contains the last character 

6 Framing error occurred on the last character 
received 

7 Break sequence (extended null character) was 
received 
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ATX Function Code 97 

Channel A Transmit 


Outputs a single character to Serial Channel A. 

TRSDOS-II sets up ATX r ARCV, and ACTRL when you initialize 
Channel A with RS232C. If you call any of these SVCs while 
the channel is not initialized, you get an error return code 
of 1 (no function code exists). 

TRSDOS-II transmits data bytes even if no carrier is 
present. You must check the status flags and Register A for 
error conditions. "Carry flag set" (C flag) means that no 
carrier is present during transmission. You may ignore this 
flag if your application does not need the carrier to be 
present. 

Register A contains status information after serial output 
(upon return from ATX). 

Entry Conditions 
A =97 

B = character to be sent, (ASCII code) 


Exit Conditions 

A = status code 

NZ = Character is not transmitted, check the 

status code 

C flag = Modem carrier was not present when you entered 
the SVC 


The 8-bit grouping of flags returned in Register A (after 
serial output) consists of: 

Bit Meaning 


0 Clear to Send (CTS) was not present 

1 Not used 

2 Transmitter busy 

3 Modem carrier was not present 

4* Parity error on the last character received 

5* Data is lost because of a hardware-level 

overflow 


Radio /hack-- 


3/35 













TRSDOS-II 


REFERENCE MANUAL 


Bit 


Meaning 


6* Framing error occurred on the last character 

received 

7* Break sequence (extended null character) 

was received 

* TRSDOS-II returns bits 4 through 7 only when it does 
not send the character. 
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TRS-80 


BCTRL Function Code 101 

Control Channel B 

Performs control functions on Serial Channel B. 

TRSDOS-II sets up BRCV, BTX, and BCTRL when you initialize 
Channel B with RS232C. If you call any of these SVCs while 
the channel is not initialized, you get an error return code 
of 1 (no function code exists). 

Entry Conditions 
A = 101 

B = options switch 

Exit Conditions 

NZ = Error 

B = status code 


Valid option switch settings are: 
option 

switch Result 


0 Gets the current status of the serial I/O 

channel into Register B. 

1 Gets the current character count in the 
serial receive buffer into B. 

2 Turns on Request To Send. RTS is on when 
channel is initialized. 

3 Turns off RTS. 

4* Starts transmitting the break sequence. 

5 Stops transmitting the break sequence. 

6 Resets the serial receive buffer count to 
zero. 

7 Resets the SIO error condition. 


* Before transmitting a break sequence, make sure the 
sure the transmit buffer is empty. As the programmer, 
you are responsible for sending the break sequence for 
the appropriate time period, as required by the 
application or host computer. 
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The 8-bit grouping of flags 
of: 


returned in Register B consists 


Bit Meaning 


0 Clear to Send (CTS) is not present 

1 Unused 

2 Transmitter is busy 

3 Modem data carrier is not present 

4 Parity error is occurring in the byte that is 
being received 

5 Data is lost because of an overflow caused by a 
byte that is being received 

6 Framing error occurred in the byte that is 
being received 

7 Break sequence (extended null character) was 

received 
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Binary/Decimal 

Converts a 2-byte binary number to an ASCII-coded decimal, 
and vice versa. The decimal range is from 0 to 65535. 

Entry Conditions 
A =21 

B = function switch 

B = 0: convert binary to ASCII decimal 
B / 0: convert ASCII decimal to binary 

If B = 0 (binary to decimal): 

DE = 2-byte binary number to convert 
(HL) = 5-byte area to contain the ASCII decimal value 
The field contains decimal digits in the range 

[X'30',X'39'], with leading zeroes on the left 
as needed to fill the field. For example, 00021 
represents 21. 

If B / 0 (decimal to binary): 

(HL) = 5-byte area containing the ASCII decimal value 
to convert 

Exit Conditions 

(HL) = decimal value 
DE = binary value 
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BINHEX 

Binary/Hexadecimal 



Function Code 24 


Converts a 2-byte binary number to an ASCII-coded 
hexadecimal, and vice versa. The hexadecimal range is from 
X '0000 ' to X'FFFF'. 


Entry Conditions 
A =24 

B = function switch 

B = 0: convert binary to ASCII hexadecimal 
B / J3: convert hexadecimal to binary 

If B = 0 (binary to hexadecimal): 

DE = 2-byte binary number to convert 
(HL) = 4-byte area to contain the ASCII hexadecimal 
value 

The field contains hexadecimal digits with 
leading zeroes on the left, as needed to fill 
the field. For example, 00FF represents the 
number X'FF'. 


If B ^ 0 (hexadecimal to binary): 

(HL) = 5-byte area containing the ASCII hexadecimal 
value to convert 


Exit Conditions 

(HL) = hexadecimal value 
DE = binary value 
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BRCV Function Code 98 

Channel B Receive 

Returns a single character from Serial Channel B. 

TRSDOS-II sets up BRCV, BTX, and BCTRL when you initialize 
Channel B with RS232C. If you call any of these SVCs while 
the channel is not initialized, you get an error return code 
of 1 (no function code exists). 


Input Buffer 

Each channel (A and B) has an internal receive buffer to 
reduce overruns when receiving data at high speeds. This 
buffer is a first-in, first-out buffer (FIFO) which is 
established when the channel is initialized. 

When a character is received, the character and the hardware 
status code are placed in the Channel B buffer. If Channel 
B has not been initialized, no characters are received. 

An overrun occurs when a character is received and there is 
no more room in the buffer. The character that caused the 
overrun replaces the last character received. Bit 5 of the 
hardware status code is set; this indicates that an overrun 
occurred. 

When the BRCV SVC is executed, the oldest character in the 
buffer is returned to Register B; the hardware status at the 
time the character was received is returned to Register A. 

Note: When a character that caused an error is 

returned to Register B, the error is indicated in 
Register A. 

If there are no characters "waiting" in the buffer, the 
communications status returned in Register A reflects the 
current status of the serial interface. 

Entry Conditions 
A =98 
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Exit Conditions 

A = status code 

B = character returned , if any 

NZ = Character not received; check the status 

code 

C flag = Modem carrier was not present when you entered 
the SVC 

The 8-bit grouping of flags returned in Register A (after 
serial input) consists of: 

Bit Meaning 


0 Not used 

1 Not used 

2 Not used 

3 Modem carrier was not present 

4 Parity error occurred on the last character 
received in Register B 

5 Data is lost because of an overflow; Register B 
contains the last character 

6 Framing error occurred on the last character 
received 

7 Break sequence (extended null character) was 

received 
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BTX Function code 99 

Channel B Transmit 

Outputs a single character to Serial Channel B. 

TRSDOS-II sets up BTX, BRCV, and BCTRL when you initialize 
Channel B with RS232C. If you call any of these routines 
while the channel is not initialized, you get an error 
return code of 1 (no function code exists). 

TRSDOS-II transmits data bytes even if no carrier is 
present. You must check the status flags and Register A for 
error conditions. "Carry flag set" (C flag) means that no 
carrier is present during transmission. You may ignore this 
flag if your application does not "care" whether the carrier 
is present. 

Register A contains status information upon return from BTX. 

Entry Conditions 
A =99 

B = character to be sent (ASCII code) 

Exit Conditions 

A = status code 

NZ = Character not transmitted; check the status 

code 

C flag = Modem carrier was not present when you entered 
the SVC 

The 8-bit grouping of flags returned in Register A (after 
serial output) consists of: 

Bit Meaning 


J0 Clear to Send (CTS) was not present 

1 Not used 

2 Transmitter is busy 

3 Modem carrier was not present 

4* Parity error occurred on the last character 

received 

5* Data is lost because of a hardware-level 

overflow 
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Bit 


Meaning 


6* Framing error occurred on the last character 

received 

7* Break sequence (extended null character) 

was received 

* TRSDOS-II uses Bits 4-7 only when it does not send 
the character. 
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CLOSE 


Function Code 42 


Close Disk Files 

Ends access to the file you specify. This SVC first 
writes all unsaved data to the disk, then updates the 
directory before closing the file. 

Entry Conditions 
A =42 

(DE) = data control block of the currently open file 

Exit Conditions 

NZ = Error 

A = error code 

Upon return, the filespec (except for the password) 
automatically is put back into the DCB. 
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CLRXIT 


Function Code 57 


Clear User Memory and Jump to TRSDOS 

Clears (writes binary zeroes to) user memory and gives 
control to TRSDOS-II. 

Entry Conditions 
A =57 

Exit Conditions 
None 
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CURSOR Function Code 26 

Blinking Cursor 

Turns the blinking cursor on or off. TRSDOS-II keeps track 
of the current cursor position, whether the cursor is on or 
off. 

Entry Conditions 
A =26 

B = function switch 

B = 0: blinking cursor off 
B / 0: blinking cursor on 

Exit Conditions 
None 
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DATE 

Return Date String 


Function Code 45 


Sets or returns the time and date. TRSDOS-II returns the 
data as a 26-byte ASCII string with 8 fields. 

Contents of Time/Date string: 


| Fri | Oct | 1| 1982 | 274 | 13.2J0.42 | 1J0 | 4 | 


Name Mon. Day Year Day Time Mon. Day 

of of of of of 

Day Mon. Year Year Week 

Represents the data "Friday, October 1, 1982, the 274th day 
of the year, 1:2J0:42 p.m., the tenth month of the year, the 
fourth day of the week." 

Monday is considered day J0. The date calculations are based 
on the Julian Calendar. 

Entry Conditions 

A =45 

B = function switch 

B = 0: get time/date 
B = 1: set date 
B = 2: set time 

(HL) = a dependent of the contents of Register B 
If B = 1: 

(HL) = 10-byte buffer containing the date (The date is 
in the form mm/dd/yyyy.) 

If B = 2: 

(HL) = 8-byte buffer containing the time (The time is 
in the form hh.mm.ss.) 

Exit Conditions 

NZ = Error 
If B = 0: 

(HL) = 26-byte buffer where the time/date are to be 
stored 


RadM/haek" 


3/48 
















REFERENCE MANUAL 


TRSDOS-II 


DELAY Function Code 6 

Delay Loop 

Provides a delay routine and returns control to the calling 
program after the time you specify has elapsed. 

Background processing, such as the SPOOL printing function, 
uses this delay time. 

Entry Conditions 
A =6 

BC = delay multiplier switch 

BC = 0: the delay time is 426 milliseconds 
BC / 0: the delay time is: 

6.5 * (BC - 1) + 22 microseconds. 


Exit Conditions 
None 
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DIRRD Function Code 35 

Direct-Read 

Reads the specified record of an FLR file. 

Also, you can use DIRRD to read the first record or the EOF 
(X'FFFF') of a VLR file. 

Upon return, your record is in the record area pointed to by 
RECADR in the parameter list. Or, if the record length is 
256, and you are reading a fixed-length record, it is in the 
area pointed to by BUFADR (see the OPEN SVC for more 
information). 

Entry Conditions 
A = 35 

(DE) = data control block of the currently open file 
BC = record number 

BC = 0 : position to beginning of file 
BC = X'FFFF': position to end of file 
HL = Reserved 

If you chose the E mode when you opened the file, then: 

BC = address of 3 bytes in RAM The format is: 


upper 

middle 

lower 

byte 

byte 

byte 


where 00 00 00 = first record of file 
and FF FF FF — end of file (EOF) 


Exit Conditions 

NZ = Error 

A = error code 
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DIRSET Function Code 59 

Directory Information 

Gets directory information on any open file. 

DIRSET sets up the 8-byte block of memory that is one of the 
entry parameters for the RDDIR SVC. After you open the 
file, you can: 

1. Find out which drive contains the file (See the 
RDDIR SVC). 

2. Set up the 8-byte block in user memory (BC) for 
RDDIR. This lets RDDIR get directory information 
about the open file. 

Entry Conditions 
A =59 

DE = address of the open data control block 

BC = address of the 8-byte block of user memory 

Exit Conditions 

All registers return unchanged, except Register A. 

BC = address of the 8-byte block of user memory set 
for RDDIR call to get the directory information 
of the open data control block (pointed to by 
DE) 

Z = No error 

NZ = I/O error 

A = error code 

Note: Be sure to load Register Pair DE with zero (LD DE,J0) 

after executing DIRSET and before executing RDDIR. If DE is 
non-zero, RDDIR expects a wildcard mask and, in most cases, 
cannot find a match. 
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DIRWR 


Function Code 44 


Direct-Write 

Writes a specified record to a specified position in an FLR 
file. Also, you can use DIRWR to write the first record ( 0 ) 
or the EOF (X'FFFF') record in a VLR file. 

Before calling DIRWR, put your record into the record area 
pointed to by RECADR in the parameter list. Or, if the 
record length is 256 and the record type is fixed, put the 
record in the area pointed to by BUFADR (see the OPEN SVC 
for more information). 

Entry Conditions 
A =44 

(DE) = data control block of the currently open file 
BC = record number 

BC = 0 : position to beginning of file 
BC = x'FFFF': position to end of file 
(HL) = Reserved 

If you chose the E mode when you opened the file, then: 

BC = address of 3 bytes in RAM The format is: 


upper 

byte 


middle 

byte 


lower 

byte 


where 00 00 00 = first record of file 

and FF FF FF = record after current EOF (EOF +1) 


Exit Conditions 


NZ = Error 

A = error code 
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DISKID 

Read Disk ID 


Function Code 15 


Reads the diskette ID(s) from any or all of Drives J0-7. 

This is useful when the program must ensure that the 
operator has inserted the proper diskette. 

TRSDOS-II places the diskette ID(s) in the buffer pointed to 
by Register Pair HL. If a drive is not ready, TRSDOS-II 
places blanks in the buffer. If you specify 255, TRSDOS-II 
reads the IDs from all drives. If you have do not have hard 
disks, the last 32 bytes of the buffer are blank. 


Entry Conditions 


A =15 

B = drive select code 

B = jZf-7: read from specified drive (J0-7) 
B = 255: read all disks' IDs 
(HL) = disk ID buffer 

If B = J0-7: 

The buffer must be 8 bytes long. 

If B = 255: 

The buffer must be 64 bytes long. 

Exit Conditions 

(HL) = disk ID(s) 

NZ = Error 

A = error code 
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DOSCMD 

Execute TRSDOS-II Command 


Function Code 37 


Passes a command string to TRSDOS-II Ready mode for 
execution. After the command is executed, control returns 
to TRSDOS-II. All open files are closed automatically. 

Entry Conditions 
A =37 

(HL) = command string 
B = length of string 

Exit Conditions 


None 
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TRS 


ERRMSG 


Function Code 52 


Error Message 

Returns an 80-byte error description to the specified buffer 
area, in response to the specified error number. 

Entry Conditions 
A =52 

B = error number 

(HL) = 80-byte buffer area above X'27FF' 

Exit Conditions 

NZ = Error 

A = error code 
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ERROR 


Function Code 39 


Display Error Number 

Displays the message ERROR, followed by the specified error 
code, at the current cursor position. 

Entry Conditions 
A =39 

B = error number 


Exit Conditions 

NZ = Error 

A = error code 
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FILPTR Function Code 58 

Get Pointers of a Open File 

Gives information on an open user file. If it does not make 
a match, the SVC returns an error. 

Note: We recommend restricting your use of the FILPTR 

since this SVC is restricted to 96 files. If you are 
familiar with FILPTR, you should change your existing 
programs to use RDDIR instead. 

Entry Conditions 
A =58 

(DE) = data control block of the currently open 

file 

Exit Conditions 

Z flag = No error 

NZ = Error 

B = drive that contains the file (binary 0-7) 

C = position of the file in the diskette 

directory (binary 1-96) 

Notes 

This SVC is intended for use with the RAMDIR SVC. After 
opening a file, you may: 

1. Use FILPTR to find out which drive contains the 
file and which directory record contains the 
file's information. 

2. Use RAMDIR to obtain information about that 
file (current file space allocated/used, 
protection level, and so on). 
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HLDKEY Function Code 29 

Enable the <HOLD> Key 

Suspends and restarts terminal output whenever you press 
<HOLD>. 

This SVC must first be enabled; call the SVC with B = 1. You 
must periodically call the SVC to see if the <HOLD> key has 
been pressed; call the SVC with B > 1. This places the 
program in control of the pause checking. If <HOLD> has 
been pressed, the program pauses until <HOLD> is pressed 
again. 

Returning to the TRSDOS-II READY command level turns off the 
<HOLD> processor. However, you can execute a command 
without turning off the <HOLD> processor. See the JP2D0S 
and DOSCMD SVCs for ways to execute a command. 

Some library commands and utilities, including DIR and LIST, 
reset the <HOLD> processor. 

No matter how many times you press <HOLD> before you call 
HLDKEY, TRSDOS-II interprets it as one keystroke, thus 
starting the pause. 

Entry Conditions 
A =29 

B = function code 


The HLDKEY function codes are: 
Contents 

of B Meaning 


0 Turns off the <HOLD> processor. Pressing 

<HOLD> generates X'00'. 

1 Turns on the <HOLD> processor. Pressing 

<HOLD> does not generate keyboard data. 
TRSDOS-II intercepts it. 

>1 Checks for the <HOLD> key. If you have 

pressed it, TRSDOS-II pauses until you press 
it again. 


Exit Conditions 

NZ = <HOLD> processor is off 


Radio/haod 


3/58 











TRSDOS-II 


TRS 


80 


REFERENCE MANUAL 


INITIO 


Function Code fS 


Initialize I/O 

Initializes all input/output drivers. 

This SVC is already done by TRSDOS-II. You do not need to 
call it, except in extreme error conditions. 

Entry Conditions 
A = 0 

Exit Conditions 

NZ = Error 

A = error code 
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TRS 


80 



JP2D0S 


Function Code 36 


Jump to TRSDOS-II 

Returns control to TRSDOS-II, after closing all open files 
and doing system housekeeping. 

Another way to do this is to execute an RST 0 instruction. 
There are no entry conditions for this method. 

Entry Conditions 
A =36 

Exit Conditions 
None 
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TRSDOS-II 


80 


® 


TRS 



KBCHAR 


Function Code 4 


Keyboard Character 

Gets one character from the keyboard. If characters are 
present in the key-ahead buffer, the first character in the 
buffer is returned to Register B. 

The <BREAK> key is masked from you. It is never returned, 
since it is intercepted by TRSDOS-II. If you enable a 
SETBRK routine, control passes to the processing program 
whenever <BREAK> is pressed (see the SETBRK SVC). 

Otherwise, control passes to TRSDOS-II READY. 

Entry Conditions 
A =4 

Exit Conditions 

B = character found (if any) 

If no character is returned, B is unchanged. 

NZ = No character is present 

A = error code 
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KBINIT 


Function Code 1 


Keyboard Initialize 

Initializes the keyboard input driver. You might want to 
call KBINIT before starting keyboard input, to clear 
previous keystrokes and the key-ahead buffer. TRSDOS-II 
automatically does this at startup. 

Entry Conditions 
A =1 

Exit Conditions 

NZ = Error 

A = error code 
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KBLINE Function Code 5 

Keyboard Line 

Inputs a line from the keyboard to a buffer and echoes the 
line to the display, starting at the current cursor 
position. As it receives and displays each character, 

KBLINE advances the cursor to the next position. 

When you enter KBLINE, the input buffer contains a string of 
periods, which it sends to the display. This string is for 
your convenience. It indicates the length of the input 
field. 

The keyboard line ends when you press <ENTER> or when the 
input buffer is filled. When you end the line input, KBLINE 
sends a carriage return and an "erase to end of screen" 
command to the display. It stores a carriage return as a 
character input only if you press <ENTER>. 

Entry Conditions 
A =5 

(HL) = input buffer 

B = maximum number of characters to receive 
(1-255) 

Exit Conditions 

B = actual number of characters input (including 
carriage return) 

C = terminating character of input 

C = X'00'i input buffer is filled without a 
carriage return 

C = X'0D': line ended with a carriage return 

If you type a control code not listed below, KBLINE places 
it in the buffer and represents it on the display with the 
+ symbol. 


Key 


Hex 

Code 

Function 


<BACKSPACE> 

08 

Backspaces the cursor 
character. 

and erases a 

<ENTER> 


0D 

Ends the line. Clears 
on the display but not 

trailing periods 
in the buffer. 
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Hex 

Key Code Function 


<CTRL> <W> 


<CTRL> <X> 


<ESC> 


17 Fills the remainder of the input buffer 
with blanks. Blanks the remainder of 
the display line. 

18 Fills the remainder of the input buffer 
with blanks. Blanks to the end of 

the display. 

IB Reinitializes the input function by 

filling the input buffer with periods 
and restoring the cursor to its original 
position. 


<left arrow> 


1C Backspaces the cursor to allow editing 

of the line. Does not erase characters. 


<right arrow> ID 


Advances the cursor to allow editing of 
the line. Does not erase characters. 
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KBPUT Function Code 30 

Put Character into Key-Ahead Buffer 

Puts one character into the keyboard key-ahead buffer, in 
the same manner that pressing that key on the keyboard does. 

The character is placed after any characters already in the 
buffer. 

If the character is X’00', TRSDOS-II puts it into the buffer 
if HLDKEY is off. If HLDKEY is on, X'00' triggers hold 
processing. (See the HLDKEY SVC.) 

If the character is X'03' , it invokes the <BREAK> key 
processing. (See the SETBRK SVC.) 

Entry Conditions 
A = 30 

B = character to be put into the buffer 

Exit Conditions 

Z = Character is put into the buffer 
NZ = Buffer is full; the character is not in the 
buffer 

A = error code 
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KILL 


Function Code 41 


Delete File From Directory 

Deletes the specified file from the directory. You must 
close a file before you can KILL it. 

Entry Conditions 
A =41 

(DE) = data control block 

Exit Conditions 

NZ = Error 

A = error code 
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LOCATE 


Locate Record 


Function Code 33 


Returns the number of the current record (the last record 
accessed). You can use LOCATE only with FLR files. 

Entry Conditions 
A =33 

(DE) = data control block of the currently open file 
HL = Reserved 

Exit Conditions 

BC = current record number 

NZ = Error 

A = error code 

If you chose the E mode when you opened the file, then: 

BC = address of 3 bytes in RAM where the record 
number is to be stored, in the following 
format: 





upper 

middle 

lower 

• 

byte 

byte 

byte 


where 00 00 00 = first record of file 
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LOOKUP 

Look Up in a Table 


Function Code 28 


Does a lookup function on a table of 3-byte entries. Each 
entry looks like this: 


Byte 1 
Search Key 


Byte 2 | Byte 3 

Data, e.g., address in LSB, MSB sequence 


At the end of the table, you must place a 1-byte X'FF'. 
Since X'FF' is the table terminator, your search keys must 
be between X'00' and X'FE'. 

Given a 1-byte search argument, LOOKUP locates the first 
matching entry in the table. It uses a sequential search 
algorithm. 

If the table contains search keys followed by addresses, 
then (upon return from the routine with the Z flag set) you 
can JP (HL) to transfer control to the desired address. 

Entry Conditions 
A =28 

(HL) = byte 1 of the table 

B = search argument 

Exit Conditions 

NZ = Search argument is not found 

HL = data 

H contains byte 3 
L contains byte 2 
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MPYDIV 

Multiply Divide 


Function Code 23 


Multiplies or divides with one 2-byte value and one 1-byte 
value. 


Entry Conditions 
A =23 

B = function switch 


If B = 0: multiply 

HL = multiplicand 

C = multiplier 


If B / 0: divide 

HL = dividend 

C = divisor 

Exit Conditions 
If B = 0: 

HL = product (HL * C) 

C flag = Overflow occurred 

A = overflow byte 

Z = Product is 0 

If B / 0: 

HL = quotient (HL/C) 

C = remainder 

C flag = Dividing by 0; division is not attempted 
Z = Quotient is 0 
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OPEN Function Code 40 

Open File 

Creates new files and opens existing files. 

A given file can be open under only one data control block 
(DCB) at a time. Because of the versatile file processing 
routines, this one DCB is enough to handle the various I/O 
applications. 

Entry Conditions 
A =40 

(DE) = data control block 
(HL) = parameter list 

Exit Conditions 

NZ = Error 

A = error code 

Before calling OPEN, you must reserve space for the data 
control block, parameter list, buffer area, and record area. 

Data Control Block (60 bytes) 

The data control block (DCB) is used by TRSDOS-II for file 
access bookkeeping. Use it specify the filespec when 
opening a file. 

Before calling OPEN, place the filespec at the beginning of 
the DCB, followed by a carriage return. (See "File 
Specification" in the "Introduction.") 

For example: 

Contents of First Bytes of DCB Before Open 
($ signifies a carriage return) 


|f i 1 e n a m e/e xt . pas sword :d (disk name) $ 


While a file is open, TRSDOS-II replaces the filespec with 
information TRSDOS-II uses for bookkeeping. When you close 
the file, TRSDOS-II returns the original filespec (except 
the password) to the DCB. 
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Never modify any part of the DCB while the file is open. 
The results are unpredictable. 


Parameter List (11 bytes) 

Contents of Parameter List (sample) 


| 00 70 | 00 70 | 08 58 | "W" | 80 | "F" | 2 | 00 | 


BUFADR RECADR EODAD Access RL File User 

Type Type Attribute 

Creation 
Code 


BUFADR (Buffer Address) 

Two-byte field that points to the beginning of the buffer 
area. 

The buffer area is the space TRSDOS-II uses to process all 
file accesses. When spanned records are required, you must 
reserve 512 bytes. When spanning is not required, reserve 
only 256 bytes. 

With FLR files, spanning is required only when the record 
length is not an even divisor of 256. For example, if the 
record length is 64, then each physical record contains four 
records, and no spanning is required. In this case, reserve 
only 256 bytes for processing. 

However, if the record length is 24 (not an even divisor of 
256), then some records must be spanned. In this case, 
reserve 512 bytes. 

With VLR files, you must reserve 512 bytes for processing. 
Spanning may be required, depending on the lengths of the 
records. 


RECADR (Record Address) 

Two-byte field that points to the beginning of the record 
area. 


Radio /hack 


3/71 













TRSDOS-II 


REFERENCE MANUAL 



This is where TRSDOS-II places the record after a disk read 
and where you would put the record to be written to disk. 

For FLR files with a record length of 256, RECADR is not 
used. Your record is in the buffer area pointed to by 
BUFADR. 

If you have an FLR file with a record length not equal to 
256, make this buffer the same length as the record. 

If you have VLR files, be sure to make the buffer long 
enough to contain the longest record in the file (including 
the length byte). If you are not sure of the length, 
reserve 256 bytes. 


EODAD (End of Data Address) 

Two-byte field which can be used to give TRSDOS-II a 
transfer address to use in case TRSDOS-II reaches the EOF 
during an attempted read. 

Control transfers to the EODAD if this happens. If EODAD = 
0 and the EOF is reached, the SVC returns with the EOF error 
code in Register A. 


Access Type 

Specifies the type of access you desire. It can be any of 
the following: 

ASCII 

Character Meaning 


R Read only 

W Read/Write (data files) 

P Read/Write access to Z8J3 program files 

If OPEN finds a program file, TRSDOS-II returns a P in the 
read/write field in the parameter list. For example, a call 
to OPEN with a parameter list of: 

0070 0070 0858 R 80 F 0 00 
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TRSDOS-II 


returns the following, if the file found is a program file: 
0070 0070 0858 P 80 F 0 00 


RL (Record Length) 

One-byte field that specifies the record length to be used. 

Zero indicates a record length of 256. For VLR files, ignore 
this field. If the file exists, and the creation code is 0, 
TRSDOS-II supplies the correct RL value, regardless of what 
is stored there. 


File Type 

One-byte field that contains an ASCII "F," "V," or "E" (for 
"fixed-length," "variable-length," or "extended mode"). 

Once a file exists, this attribute cannot be changed. If 
the file exists, and the creation code is 0, TRSDOS-II 
supplies the correct F, V or E value. 

If you specify E, then DIRRD, DIRWR and LOCATE use a 24-bit, 
indirect, 3-byte number. The E specifies FLR records and an 
extended mode of specifying record numbers. The directory 
shows F, even though you specify the E mode. 


Creation Code 

One-byte field that contains a binary number "0,” "1," or 
" 2 ." 

Code Meaning 


0 Opens the existing file, but does not reset the 

record length and EOF. 

1 Creates a new file. Returns an error if a file of 

the same name already exists on the specified 
drive. Sets the record length and EOF at OPEN. 
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Code Meaning 


2 


Opens a file, overwriting any existing file of the 
same name. Otherwise, it creates a new file. 
Resets the record length and EOF. 


User Attribute 

Lets you give your own ID number to certain types of data 
files. You can use any number from 32-255. 

TRSDOS-II does not examine this user attribute. It is 
solely for your convenience. 

You can assign this user attribute only to files you open 
with a creation code of 1 or 2. Files opened with a 
creation code of 0 retain the file's previously assigned 
user attribute. Any file created with the CREATE command 
has a user attribute value of 0. 
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PARSER Function Code 46 

Analyze Text Buffer 

Analyzes or "parses" a text buffer into fields and 
subfields. 

PARSER is a convenient and powerful SVC. It is useful for 
analyzing TRSDOS-II command lines, including keyword 
commands, file specifications, keyword options and 
parameters. You can use it also as a fundamental routine 
for a compiler or text editor. 

Entry Conditions 
A =46 
(HL) = text buffer 
(DE) = list address block 

DE = J0: no lists are to be used 
C = maximum length of the parse 

Exit Conditions 

(HL) = field position 

If a delimited field was found: 

(HL) = first byte of the field 
If no field was found: 

(HL) = terminator or non-blank separator 
If the parse reached the maximum length: 

(HL) = last byte of the buffer 
B = actual length of the field (excluding leading 
and trailing blanks) 

A = character preceding the field just found 
If B = 0 , A = X'FF'. 

C = number of bytes remaining to parse after the 
terminator or separator (trailing blanks have 
been parsed). 

D = separator or terminator at the end of the 
field 

If D = X 1 FF', then the parse stopped without 
finding a non-blank separator or terminator. 

E = displacement pointer for the next parse call 

Add the displacement pointer (E) to the field position 
(HL) to get: 

a) Beginning address of the next field, or 

b) Address of the byte following the last byte parsed 

If the parse reached the maximum length: 

E + HL = address following the end of the text buffer 
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If the parse did not reach the maximum length, and E = 1: 

E + HL = address following the separator or terminator 

If the parse did not reach the maximum length: 

Z flag = Parse ended with a separator 

NZ = Parse ended with a terminator 

C flag = There were trailing blanks between the end 

of the field and the next non-blank separator 
or terminator 

NC = There were no trailing blanks 

PARSER is designed to allow repetitive calls for processing 
a text buffer. On exit from the parse, parameters for the 
next call are all readily available in the appropriate 
registers. 


Field 

A field is any string of alphanumeric characters 
(A-Z, a-z, J0-9) with no embedded blanks, delimited by 
separators and terminators. 


Separators and Terminators 

Separators and terminators are used to delimit (or separate) 
fields within a text buffer. PARSER has pre-defined sets of 
field-characters and separators. You either can use these 
or re-define them to suit your application. 

For example, the line: 

BAUD=3jJ0, PARITY=EVEN W0RD=7 

contains 6 fields: BAUD, 300 , PARITY, EVEN, WORD, and 7. 

A separator is any non-alphanumeric character. PARSER stops 
when it encounters a separator, except when the separator is 
a blank (X'20'). PARSER ignores leading and trailing 
blanks. After the trailing blanks, the parse stops at the 
beginning of the next field or at the first non-blank 
separator. 
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You can also define terminators, which stop PARSER 
regardless of whether it has found a field. Unless you 
specifically define these terminators, the parse stops only 
on non-blank separators. 

Separators and terminators have the same effect on a parse. 
The only difference is in how they affect the F (Flag) 
register on exit. 

A field can be delimited by paired quotation marks, also: 
"field" or 'field' 

When you use quotation marks, all characters (not just 
alphanumerics) are taken as part of the field. The 
quotation marks are not included in the field. For example: 

'DATE(07/11/79)' 

is interpreted as one field that contains everthing inside 
the quotation marks. 

When you use a quotation mark to mark the start of a field, 
you must use the same kind to end the field. This lets you 
use quotation marks within a field. For example: 

"X'FF00'" 

is parsed as one field that contains everything inside the 
double quotes, including the single quotes. 


To Re-define the Field, Separator, and Terminator Sets 

If you need to change the field and separator sets, or 
define terminators, you can provide three change-lists via 
a list address block. 


List Address Block 

The list address block is six bytes long and contains 
three 2-byte addresses (LSB,MSB), one for each change-list: 
List 1: characters to be used as terminators 
List 2: additions to the set of field characters 
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List 3: deletions from the set of field characters 
(alphanumeric^ to be interpreted as 
separators) 


Each list has the following form: 



Notes 


There are three ways to indicate a null list: 

a) Set the character-count byte (n) equal to 
zero. 

b) Set the pointer in the list address block to 
zero. 

c) Set DE equal to zero, if you aren't going to 
provide any lists. 

Characters are stored in lists in ASCII form. 

If a character appears in more than one list, it 

has the characteristics of the first list that 

contains it. 
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Here is 
lists. 


a typical list address block with its associated 
Assume that on entry to PARSER, DE = X'8000'. 


X’8000’ 


0090 


10 90 


2090 


Start Start Start 
of of of 
list 1 list 2 list 3 


X’9000 



X’9010’ 



X’9020 



in list 2 
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Sample Programming 


The following code shows typical repetitive uses of PARSER 
to break up a parameter list. 


LD 
l D 
LD 

• ™ _ __ „ „ ™ „ 

* 

PARSE CALL 
CALL 
JR 

LD 

OR 

JR 

LD 

CP 

JR 

JR 

" 

HANDLR PUSH 


PREPARE FOR 
C? MAXLEN 
E? 0 

HL?BUFFER 
PARSE LOOP— 
NXTFLD 
HANDLR 
NZ ? NXTRTN 

A? C 
A 

NZ ? PARSE 
A? 0FFH 
D 

ZiERR 

NXTRTN 

FIELD-HANDL 

AF 


PARSING LOOP- 

C = Maximum length to parse 
For initial call to NXTFLD 
<HL) :: = string to parse 

Routine to call PARSER 
Routine to handle new field 
Go to next routine if 
parsed ended on terminator 
Else get new max length 
Is it zero? 

If not? then continue 

If D-0FFH then no separator 
at end of buffer. 

So go to error routine 
Else? then do next routine. 

ING ROUTINE- 

Must save status registers 
and any other registers 
will be changed. 


? P r o c e s sin g cod e g o e s here... 
POP AF 


Restore AF (and other- 
registers saved at entry) 


RET 


CALL TO PARSER- 


NXTFLD 

LD 

D? 0 

5 Zero msb of DE 



ADD 

HL ? DE 

; <HL) = where to start 

parse 


LD 

DE? LAB 

; (DE) = List address bl 

o c k 




; If DE-0 then no lists 

used . 


LD 

A ? 46 

* Function Code 



RST 

8 




RET 




7 

— 

-PROGRAM CONTINUES 

HERE- 

-- 

NXTRTN 

EQU 

$ 
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PRCHAR 

Print Character 


Function Code 18 


Sends one character to the printer. 

Notes Most printers do not print until their buffer is 
filled or they receive a carriage return. (See your 
printer's manual for information.) 

Normally, TRSDOS-II intercepts certain codes and does not 
send them directly to the printer. There are several ways 
to override some or all of these character translations. 
(See the PRINIT and PRCTRL SVCs.) 


While the serial printer option is selected, allowing 
printer output to Channel B, TRSDOS-II recognizes two 
characters from Channel B. These affect all serial di 


output operations: 

ASCII 

Name 

Hex 

Code 

Result 

DC3, <CTRL> <S> 

13 

Pauses printing 

DC1, <CTRL> <Q> 

11 

Resumes printing 

Entry Conditions 



A =18 



B = ASCII code 

for the 

character to send 


Exit Conditions 

NZ = Error 

A = error code 
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INTERCEPTED CODES 


ASCII 

Hex 


Name 

Code 

Result to Printer 

Tab 

09 

Sends one to eight spaces to provide 
the tab function. 

Vertical Tab 

0B 

Same as form feed below. 

Form Feed 

0C 

Sends enough carriage returns 
or line feeds to advance the paper to 
the next "top of form." 

Carriage 

0D 

Interpreted as a line feed when the 
current line is empty (no characters are 
printed since the last carriage return 
or line feed). This interpretation 
enables the correct operation of Radio 
Shack printers. In the auto line-feed 
mode, X'0A' is sent after every X'JJD'. 

Special 

8D 

Sends a carriage return to the 


printer. In the auto line-feed mode, 
using this code lets you send a 
carriage return without a line feed. 
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PRCTRL 


Control Printer Operations 


Function Code 95 


Gives you various printer options and lets you check the 
status of printer-related functions. 


If you use SPOOL'S capture function, TRSDOS-II sends the 
captured data directly to the capture file — regardless of 
which control settings you select. If you use SPOOL'S print 
function, TRSDOS-II intercepts the printed data to the 
selected control settings. (See the SPOOL command for 
details.) 

By switching between the serial and parallel output modes, 
you can operate with two printers. One printer can use the 
automatic control features of TRSDOS-II, such as the auto 
form feed, while the other printer is controlled by the 
program. This is necessary because only one set of control 
counters is maintained. 


Entry Conditions 



A 

C 

B 


= 95 

= option value (used with option codes 3 
and 4) 

= option code 


Exit Conditions 

Z flag = No error 

NZ = Error 

B = physical page length 

C = logical page length 

D = logical line length 

E = printer option 

E = P: parallel printer 
E = S: serial printer 

H = number of characters printed on the present 

line 

L = number of lines printed on the present page 


(See the PRINIT SVC for details on physical and logical page 
length and logical line length.) 
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The option codes are: 
Code Option 


0 Gets printer status only (see "Exit Conditions") 

1 Selects the serial printer driver (you must 
initialize Channel B first) 

2 Selects the parallel printer driver 

3 Resets the current line count to the value 
contained in Register C 

4 Resets the current character count on current line 
to the value contained in Register C 

5 Begins the transparent mode 

6 Ends the transparent mode 

7 Begins the dummy mode 

8 Ends the dummy mode 

9 Begins the auto line-feed (after carriage return) 
mode 

10 Ends the auto line-feed (after carriage return) 
mode 


Explanation of Options 


Serial/Parallel Printer Option 

While the serial printer option is selected, allowing 
printer output to Channel B, TRSDOS-II recognizes two input 
characters from Channel B. These affect all serial printer 
output operations: 


ASCII 


Hex 



Name 


Code 

Result 


DC3, <CTRL> 

<S> 

13 

Pauses 

printing 

DCl, <CTRL> 

<Q> 

11 

Resumes 

printing 


Line Count/Character Count 

TRSDOS-II maintains a single line counter and a single 
character counter. It updates these for either serial or 
parallel printing. TRSDOS-II does not maintain separate 
counters for serial and parallel printing. 
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Transparent Mode 

The transparent mode overrides all data translation. All 
data bytes go directly to the printer. TRSDOS-II does not 
examine the contents or update the line and character 
counts. 

Normally, TRSDOS-II "intercepts" certain control characters 
and interprets them. In this way, TRSDOS-II provides 
printer-related features which may not be available from the 
printer. 

For example, tabs (X*J09' ) are intercepted so that TRSDOS-II 
can send the appropriate number of spaces to provide the tab 
function. Form feeds (X'J3C or X'0B') are intercepted so 
that TRSDOS-II can advance the paper to the next top 
of form. 

Special settings of the printer initialization values can 
override individual code translation. (See the PRINIT SVC 
for details.) 


Dummy Output Mode 

The dummy mode "throws away" all printer output and returns 
with a "good" (Z flag set) return code. During dummy mode 
operation, the line and character counts remain unchanged. 


Auto Line Feed 

Normally, the TRSDOS-II printer driver does not output 
line feeds after carriage returns, because most Radio 
Shack printers do an automatic line feed after every 
carriage return. 

If your printer does not do automatic line feeds after 
carriage returns, you may enable the TRSDOS-II auto 
line-feed function. 

While the function is enabled, TRSDOS-II outputs a line feed 
after each carriage return. This is true in all modes 
including the transparent mode. 
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Note: In the auto line-feed mode, you may send a carriage 

return with no line feed by outputting the code X'8D'. If 
the printer is capable of overprinting, this code returns 
the carriage without advancing the paper. 


Precedence of Options 

The priority of the available options is (in descending 
order): 

SPOOL capture mode (See the SPOOL command) 

Dummy mode 

Auto line-feed (after carriage return) mode 
Transparent mode 
Normal mode 



Radio /hack 



3/86 












TRSDOS-II 


REFERENCE MANUAL 


TRS-SO ® 


PRINIT Function Code 17 

Printer Initialization 

Initializes the printer driver. 

It does not advance the printer paper and does not check 
the printer status or availability. It operates even if the 
printer is off-line. 


Entry Conditions 
A =17 

B = physical page length 

C = logical page length 

D = logical line length 

Exit Conditions 

NZ = Error 

The physical page length is the number of lines that can 
be printed on one page. It is normally 66. 

The logical page length is the number of lines you want 
printed on each page. It must be less than or equal to 
physical page length . After that number of lines is 
printed, TRSDOS-II sends a top-of-page request to the 
printer (form feed). 

The logical line length is the maximum number of 
characters to be printed on each line. Once that number is 
reached, the line is printed and a new line is begun 
(wrap-around). 

Notes 


If the logical page length = the physical page 
length and both are non-zero, TRSDOS-II does not do 
an end-of-page skip. It translates form feeds into the 
number of line feeds necessary to get to the top of the 
next page. 

If the logical page length or the physicial page 
length is zero, the other also must be zero. In this 
case, TRSDOS-II does not translate form feeds (X'J0C') 
and vertical tabs (X'J3B') into line feeds, but sends 
them directly to the printer. 
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If the logical line length is zero, then TRSDOS-II 
does not translate tab characters (X'09') into spaces, 
but sends them directly to the printer. TRSDOS-II 
maintains an internal character count, with tabs 
counting as one character. 

On exit, TRSDOS-II automatically resets the current 
line and character counts to zero. 


TRSDOS-II assumes the printer is at the top of the form 
when you execute PRINIT. 


TRSDOS-II resets the dummy and transparent modes to the 
normal mode. Auto line feed and DUAL are unaffected by 
PRINIT. 

When you power up or reset TRSDOS-II, it assumes the 
following defaults: 


Parameter (PRINIT register) Value 


physical page length (B) = 66 
logical page length (C) = 60 
logical line length (D) = 132 


The other options set during initialization are: 


Auto line-feed mode 
Dummy mode 
Transparent mode 
Parallel printer 


off 

off 

off 

on 
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PRLINE Function Code 19 

Print Line 


Sends a line of characters to the printer's buffer. The 
line can include control characters as well as printable 
data. 


See the PRCHAR SVC for a list of intercepted codes. 


Entry Conditions 
A =19 

(HL) = start of the buffer containing data and 
controls to send to the printer 
B = line length (the number of characters to send) 
C = control character (any character) to send 
after the last character in the buffer 


Exit Conditions 

NZ = Error 

A = error code 
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RAMDIR Function Code 53 

Get Disk Directory/Free Space into RAM) 

Lets you examine a disk directory entry or the first 96 
files in the directory, or it lets you determine the 
diskette's free space. The information is written into a 
RAM buffer. 

Only non-system files are included in the RAM directory. 

Note: We recommend restricting your use of the RAMDIR 

since this SVC is restricted to 96 files. If you are 
familiar with RAMDIR, you should change your existing 
programs to use RDDIR instead. 

Entry Conditions 
A =53 

B = drive number (binary 0-7) 

C = function switch 


Contents of C 

Result 


0 

Gets the entire directory into 
the format described below. 

RAM in 

1-96 

Gets one specified directory record 
(if it exists) into RAM in the format 
described below. 

255 

Gets free-space information in 
format described below. 

the 


(HL) = buffer area 

If C =0, compute the buffer size by this formula: 

Number of bytes required =34 * (# of non-system files + 1) 

Because RAMDIR can read no more than 96 non-system 
files, the largest possible directory needs a buffer 
size of 3265 bytes. 

If C = 1-96, the buffer must be 34 bytes long. 

If C = 255 (free-space info desired), the buffer must be 4 
bytes long. 

Exit Conditions 

Z flag = No error; (HL) = directory or free-space 
information 

NZ = Error (Register A contains the TRSDOS-II 

error code) 
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RAM Directory Format 

The directory is given in "records," one per file. Each 
record has the following form: 

Byte 

Number Contents Comments 

1 ASCII colon marks beginning of 

each directory record in RAM. 


2-16 filename/ <ENTER> represents a carriage 

ext:d <ENTER> return. Trailing blanks are 

added as needed to fill 15 bytes. 


17 

"F" or "V" 

Indicates fixed- or variable-length 
records. 

18 

LRL 

Logical record length 1-byte 
binary 0-255. 0 implies LRL =256 

or VLR file. 

19 

# of extents 

One-byte binary 0-16, Null files=0. 

20-21 

# of sectors 
allocated 

Binary 0-65535 in LSB-MSB sequence; 
null files = 00. 

22-23 

# of sectors 
in storage of 
data 

Binary 0-65535 in LSB-MSB sequence; 
null files = 00. 

24 

EOF byte 
(position 
of the first 
byte of the 
last record 
written) 

Binary 0-255; 0 implies the first 
byte in the last sector. 

25-26 

# of records 
written 

Binary 0-65535 in LSB-MSB sequence; 
null files = 00. 

27 

User 

attribute 

byte 

Assigned when you created the file. 
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Byte 

Number 

Contents 

Comments 



28 

Protection 

level 

Binary JZf-7. 



29-31 

Date created 

Binary year. 

month. 

day. 

32-34 

Date last 
updated 

Binary year, 

month, 

day. 


When an entire directory is given (C = 0 on entry), a number 
sign (#), instead of the expected colon (:), marks the end 
of the directory. When C = from 1 to 96, the record always 
ends after the 34th byte, without a trailing number sign. 

Free-Space List Format 

Byte 

Number Contents Comments 

1-2 # of free granules *Binary LSB-MSB sequence 

3-4 # of extents Binary in LSB-MSB sequence 

* The number of sectors equals the number of granules 
multiplied by 5. 


Radio /hack 


3/92 














TRSDOS-II 


TRS 


80 


REFERENCE MANUAL 



RANDOM 


Function Code 20 


Random 1-Byte Value Return 

This routine returns a random 1-byte value. 

TRSDOS-II uses the time/date values in computing the random 
number. This method lessens the possibility of repetition. 

Pass the routine a limit value. If the limit value is 
greater than 1, the value returned is in the range [0 ,(limit 
- 1)]. For example, if the limit is 255, TRSDOS-II returns 
a value in the range [J0,254]. If the limit value is 0 or 1, 
the value returned is 0. 

Entry Conditions 
A =20 

B = limit value 

Exit Conditions 

C = random number 

NZ = Error 
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RDDIR 

Reads in Directory Record 


Function Code 32 


Reads in one directory record from one drive at a time. It 
also lets you use a wildcard mask. TRSDOS-II puts the 
directory record into a 128-byte ASCII string in user 
memory. 

To read the directory of a specific file, use the filespec 
as the wildcard mask. (Do not use the asterisk.) RDDIR 
then searches for the file. 

(See the DIRSET SVC for details on open file directory 
information.) 

Entry Conditions 
A =32 

BC = address of the 8-byte block in user memory 
defined as: 


binary 


directory index* 

* * 

drive # 

FF 

FF FF FF FF FF 

| 00 


* = ff FF FF FF FF FF sets the index to the beginning 

of the directory 
** = end-of-list terminator 


DE = wildcard mask For example: 

MASK DEFM '*/BAS' 

DEFB 0DH ;must end with 

<ENTER> 

If DE = 0, no wildcard selection takes place. 

HL = address of the 128-byte area where data is to 
be placed 

Exit Conditions 

HL = address of the 128-byte area where data is 
placed. It is in the TRSDOS-II DIR format. 

Z = No error 

C,NZ = Error; EOF encountered 

NC,NZ = I/O error 

A = error code 
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Offset Table for HL Buffer 


Offset 


Description 

# Bytes 

0 


Length byte 

1 

1-12 


Filename 

12 

13 


File-left-open marker 

1 

16-23 


Date created 

8 

25-32 


Date updated 

8 

39-42 


Attrib 

4 

45 


File type 

1 

48-51 


Record length 

4 

53-61 


Number of records 

9 

64-70 


Sectors allocated 

7 

73-79 


Sectors used 

7 

80-127 

Reserved 

48 

Example 




LOOP 

LD 

BC,CTLBLK 



LD 

DE,MASK 



LD 

HL f IMAGE 



LD 

A,32 



RST 

8 



JR 

NZ,END ; END OR ERROR HAS OCCURRED 


(display "IMAGE") 



JR 

LOOP 


END: 

JR 

C/EOF ; INDICATES 

EOF 


(exit 

routine; otherwise, an error 

occurred) 

CTLBLK: 

DEFB 

1 ; DRIVE # 



DEFB 

-1,-1,-1 ; BEGINNING 

OF DIRECTORY 



INDEX 



DEFB 




DEFB 

0 ; END OF LIST TERMINATOR 

MASK: 

DEFM 

'*/BAS' ; FIND /BAS 

FILES ONLY 


DEFB 

0DH ; CR 


IMAGE: 

DEFS 

128 ; AREA TO STORE DIR RECORD 
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READNX Function Code 34 

Read Next Record 

Reads the record following the current record (the last 
record accessed). If you just opened the file, READNX reads 
the first record. 

Upon return, your record is in the record area pointed to by 
RECADR in the parameter list. Or, if the record length is 
256 and the record type is fixed, your record is in the area 
pointed to by BUFADR. 

Entry Conditions 
A =34 

(DE) = data control block for the currently open file 
HL = Reserved for use in later versions of TRSDOS-II 

Exit Conditions 

NZ = Error 

A = error code 
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TRS 


RENAME 


Function Code 47 


Rename a File 

Changes'the name and/or extension of a file. You cannot 
change the password. 

Both filespecs (old and new) must be terminated by a 
carriage return. 

If the old filespec is password protected, you must 
include the password. Do not include a password in the 
new filespec ; TRSDOS-II retains the old password. 

Entry Conditions 
A =47 

(HL) = old filespec 
(DE) = new filespec 

Exit Conditions 

NZ = Error 
A = error code 


Radie/haek® 


3/97 


















TRSDOS-II 


TRS 


80 


® 


REFERENCE MANUAL 


RETCMD 


Function Code 38 


Return after Command 

Sends TRSDOS-II an operator command. After the command is 
completed, your program regains control. 

Take care that TRSDOS-II doesn't overlay your program when 
it loads the command file you choose. Most TRSDOS-II 
library commands use memory below X'27FF'. A few go up to, 
but do not include, X'2FFF'. Single-drive copies use all 
user memory. 

Entry Conditions 

(HL) = command string 
B = length of string 
A =38 

Exit Conditions 

NZ = Error 

A = error code 
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REWIND 


Function Code 48 


Rewind Disk File 

Rewinds a disk file. After this SVC is executed, the next 
read/write accesses the first record of that file. 

Entry Conditions 
A =48 

DE = data control block for the currently open file 

Exit Conditions 
NZ = Error 

A = error code 
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SO 



RS232C 


Function Code 55 


Initialize RS-232C Channel 

Sets up or disables either Serial Channel A or B. Before 
you use it, be sure the correct channel is connected to the 
modem or other requirements. 

This routine sets the standard RS-232C parameters and 
defines a set of supervisor calls for I/O to the channel you 
choose. When you initialize Channel A, TRSDOS-II defines 
the following SVCs: ARCV, ATX, and ACTRL. When you 
initialize Channel B, TRSDOS-II defines BCRV, BTX, and 
BCTRL. 

Before re-initializing a channel, always turn it off. You 
may not turn off Channel A when HOST is active. 

Entry Conditions 
A =55 

(HL) = parameter list 
B = function switch 


B = 0: turn off channel 
B / 0: turn on channnel 



Exit Conditions 


NZ = Error 

A = error code 


Parameter List 

This 6-byte list includes the required RS-232C parameters: 


Channel 

Baud 

Word I Parity 

Stop 

End-of-List 


Rate 

Length | 

Bits 

Marker 


Channel — is an ASCII "A" for Channel A or "B" for 
Channel B. 

Baud Rate —is a binary value from "1" to" 8": 


1 for 110 baud 

2 for 150 baud 

3 for 300 baud 
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4 for 600 baud 

5 for 1200 baud 

6 for 2400 baud 

7 for 4800 baud 

8 for 9600 baud 


Word Length — is a binary value from "5" to "8": 

5 for 5-bit words 

6 for 6-bit words 

7 for 7-bit words 

8 for 8-bit words 

Parity — is an ASCII "E," "0," or "N" (for "even," "odd," 
or "none"). 

Stop bits — is a binary "1" or "2" for the number of stop 
bits. 

End list marker — is X'00' for the 16-character default 
buffer or X'01' for a larger buffer. 


If you specify a larger buffer, the next five bytes specify 
the receive buffer, as shown below: 


Byte 0 
Bytes 1-2 
Bytes 3-4 
Byte 5 


End-of-list marker (X'01 1 ) 
Buffer start address (LSB/MSB) 
Buffer end address (LSB/MSB) 
Terminator (X'00') 


The buffer must be at least 49 bytes long, and the entire 
buffer (both front and back) must reside below X'8000'. 


To determine the size of the buffer, use the following 
formula: 

number of characters * 2 + 15 = buffer size 

The number of characters to be stored must be at least 17. 
Remember, it must be small enough to fit below X'8000'. 
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SCROLL Function Code 27 

Protect from Scrolling 

Lets you protect part of the display from scrolling. From 0 
to 22 lines at the top of the display can be protected. 

When scrolling occurs, only lines below the protected area 
are changed. 

Entry Conditions 
A =27 

B = number of lines to protect (in range 

[ 0 , 221 ) 

Exit Conditions 

NZ = Error 

A = error code 
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SETBRK Function Code 3 

Enable and Disable <BREAK> Key 

Lets you enable the <BREAK> key by defining a <BREAK> key 
processing program. Whenever you press the <BREAK> key, 
your processing program takes over. 

On entry to the <BREAK> processing program, the return 
address of the interrupted routine is on top of the stack. 
You can return to it with a Z-80 return instruction (RET). 

All Z-80 register contents are unchanged upon entry to the 
<BREAK> program. 

SETBRK also lets you disable the <BREAK> key, by removing 
the address of the processing program. You cannot change 
processing programs while the <BREAK> key is enabled. 

You must disable the <BREAK> function (HL=J0) before setting 
HL to a new address. 

The <BREAK> key processing program must reside above 
X'27FF'. 

See "Handling Programmed Interrupts" for programming 
information. 

Entry Conditions 
A =3 

HL = address of the <BREAK> key processing program 
HL = 0: disable the <BREAK> function 

Exit Conditions 

NZ = Error 

A = error code 

If HL = 0, then: 

(HL) = address of the deleted <BREAK> key processing 
program 


Radio /hack 


3/103 















TRSDOS-II 


REFERENCE MANUAL 



SETUSR Function Code 2 

Set User 

Sets or removes a user vector, thus giving you the ability 
to add SVC functions. Function codes 96-101 are available 
for you to define, unless the serial interface is on (see 
the RS232C SVC). Function codes 102-127 are always 
available for you to define. 

Once you add an SVC function, you can call it via the RST 8 
instruction, just as you can the TRSDOS-II's SVC routines. 

Your routine must reside above X'27FF', and it should end 
with a RET instruction. 

To change an already defined function, you must first remove 
the old vector. 


You can call a non-recursive SVC (system or user-defined) 
from within a user-defined SVC. For example, do not call 
SVC 107 from within SVC 107. 


Entry Conditions 
A =2 

B = function code (95 < code < 128) 
C = set/reset code 

C = 0: remove the vector 
C ^ 0: add the vector 


If C = 0 (remove vector): 

HL = entry address of your routine 

Exit Conditions 

If C = 0 (remove vector): 

HL = removed vector address 
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SORT Function Code 56 

RAM Sort 

Sorts a list of entries in RAM. All entries must have the 
same length, from 1 to 255 bytes. The sort is done 
according to a user-defined sort-key, which you may locate 
anywhere in the entry. 


Entries with duplicate sort-keys remain in the same 
relative order. 


The routine uses a "bubble-sort" algorithm. 


Entry Conditions 
A =56 

(IX) = first byte of the first entry 
(DE) = first byte of the last entry 
B = position key within an entry 

(Zero equals the first byte of an entry.) 

C = length of each entry (C > 0) 

H = sort switch 

HL = 0: use ascending sort 
HL / 0: use descending sort 
L = length of sort-key (L > 0) 

In general, B + L must be less than or equal to C. 

Exit Conditions 

NZ = Error 

A = special error return code (not the standard 
TRSDOS-II code) 


Value in A Meaning 


1 Key end exceeds the last byte of the entry 

2 Key start exceeds the last byte of the entry 

3 Entry length = 0 (invalid) 

4 Key length = 0 (invalid) 

5 Address of first entry > address of last 
entry 
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SOUND 


Function Code 60 


Sound Output 

Turns on a single tone (approximately 1 khz) in computers 
that are capable of generating sound. 

Entry Conditions 
A. = 60 

HL = sound duration (in l/30th second) 

Exit Conditions 
None 

The sound turns off automatically after n seconds, where: 
n = HL/30 

n may vary slightly, depending on how much disk and video 
access is done while SOUND is on. 
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STCMP 

String Comparison 


Function Code 22 


Compares two strings to determine their collating sequence. 

Entry Conditions 
A =22 

(DE) = strinql 

(HL) = strinq2 

BC = number of characters to compare 

Exit Conditions 

Z flag = Strings are identical 
NZ = Strings are not identical 

C flag = string 1 (DE) precedes strinq2 (HL) in the 
collating sequence 

A = first non-matching character (in strinql ) 

When the strings are not equal, you can get further 
information from the prime registers, as follows: 


HL' = address of the first non-matching character 
in string2 

DE' = address of the first non-matching character 

in strinql 

BC' = number of characters remaining 

This includes the non-matching character. 
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STSCAN Function Code 49 

String Scan 

Searches through a specified text buffer for the specified 
string. This string can consist of any values 0-255 (it is 
not strictly alphanumeric). The scan stops on the found 
string or on the first carriage return encountered, which¬ 
ever comes first. 

Entry Conditions 
A =49 

(HL) = text area to search 

(DE) = compare string 

B = length of the compare string 

Exit Conditions 

Z flag = String is found 
NZ = Error; check Register A 

A = 0: string is not found 

A / 0: error code 

(HL) = start position of the matching string in 
the search string 
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TIMER Function Code 25 

Set Timer 

Lets you set a "seconds clock" to run at the same time as 
your program and to interrupt the program when time runs 
out. For example, you can specify the number of seconds for 
keyboard input. If input is not made within the time limit, 
TRSDOS-II interrupts the keyboard input routine. It 
interrupts, also, if you reset the timer. 

After the timer counts to zero and causes an interrupt, it 
shuts off by itself. 

See "Programming with TRSDOS-II" for information on 
interrupts. 

Entry Conditions 
A =25 

(HL) = SVC to handle interrupt 

BC = number of seconds to count down 

If HL and BC both = j0, the timer turns off. If HL = 0 and 
BC ^ 0, the time count resets to the value in BC, and 
timing continues. 

Exit Conditions 
None 
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TRS-80 ® 


VDCHAR Function Code 8 

Video Character 


Outputs a character to the current cursor position. It is a 
scroll mode routine. 


Control codes 

not listed 

below are ignored. 

Key 

Hex 

Code 

Function 

<F1> 

01 

Turns on the blinking cursor. 

<F2> 

02 

Turns off the cursor. 

<CTRL> <D> 
or <F3> 

04 

Turns on the steady cursor. 

<CTRL> <G> 

07 

Sounds bell tone for approximately 
.25 second (in computers that 
generate sound). 

<BACKSPACE> 

08 

Moves the cursor back one position 
and blanks the character at that 
position. 

<TAB> 

09 

Advances the cursor to the next tab 
position. Tab positions are at 
8-character intervals — 8, 16, 24, 
32, and so on. 

<CTRL> <J> 

0A 

Moves the cursor down to the next 
row, in the same column. 

<CTRL> <K> 

0B 

Moves the cursor to the beginning 
of the previous line. The cursor 
does not move into the 
scroll-protected area. 

<ENTER> 

0D 

Moves the cursor down to the 
beginning of the next line. 

<CTRL> <N> 
or <F7> 

0E 

Turns on dual routing. 
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Key 

Hex 

Code 

Function 

<CTRL> <0> 

0F 

Turns off dual routing. 

<CTRL> <T> 

14 

Homes the cursor to the first 
non-scroll-protected position. 

<CTRL> <W> 

17 

Erases to the end of the line. 

The cursor doesn't move. 

<CTRL> <X> 

18 

Erases to the end of the screen. 

The cursor doesn't move. 

<CTRL> <Y> 

19 

Sets the normal display mode 
(green/white on black). Remains 
normal until you reset it. 

<CTRL> <Z> 

1A 

Sets the reverse display mode 
(black on green/white). Remains 
reverse until you reset it. 

<ESC> 

IB 

Erases the screen and homes the 
cursor to Position 0. 

<left arrow> 

1C 

Moves the cursor back one space. 

<right arrow> 

ID 

Moves the cursor forward one space. 

<up arrow> 

IE 

Sets 80 characters per line and 
clears the display. 

<down arrow> 

IF 

Sets 40 characters per line and 
clears the display. 


Entry Conditions 
A =8 

B = ASCII code for the character to be output to 
the display. Character codes must be in the 

range [0,127]. 

Exit Conditions 

NZ = Error 

A = error code 
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VDGRAF Function Code 10 

Video Graphics 

Displays a buffer of characters, starting at the row and 
column you specify. It is a graphics mode routine (the 
cursor "wraps" the display). 

Displayable Characters 

This routine lets you display the 32 graphics characters 
(and their reverse images). 

The codes are numbered from 0 through X'lF' and are pictured 
in the operator's manual. Codes X'2J2f' through X'7F' are 
displayed as standard ASCII characters. 

In addition, several special control codes are available: 

Hex 


Code 

Result 


F9 

Sets the normal (green/white on black) mode. The 
cursor does not move. The mode returns to its 
previous state after the VDGRAF call is completed. 

• 

FA 

Sets the reverse (black on green/white) mode. The 
cursor does not move. The mode returns to its 
previous state after the VDGRAF call is completed. 


FB 

Homes the cursor (Row 0, Column 0). 


FC 

Moves the cursor back one space. Column = Column 
- 1. When the column = 0, the cursor wraps to 

Column 79 on the preceding row. 


FD 

Moves the cursor forward one space. Column = Column 
+1. When the column = 79, cursor the wraps to 

Column 0 on the next row. 


FE 

Moves the cursor up one row. Row = Row - 1. When 
the row = 0, the cursor wraps to Row 23. 


FF 

Moves the cursor down one row. Row = Row + 1. 

When the row = 23, the cursor wraps to Row 0. 



At exit, the cursor always is set automatically to the 
graphics position immediately after the last character 
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displayed. If the buffer length = 0, the cursor is set to 
the position specified in Register Pair BC. 

Entry Conditions 
A = 10 

B = row on the screen to start displaying the 
buffer 

B < 24. For B > 23, use B modulo 24* as the row 
position. 

C = column on the screen to start displaying the 
buffer 

In the 80 characters-per-line mode, C < 80. For 
C > 79, use C modulo 80 as the column position. 
In the 40 characters-per-line mode, C < 40. For 
C > 39, use C modulo 40 as the column position. 

D = buffer length (in range [0,255]) 

(HL) = beginning of the text buffer 

The buffer should contain codes below X'80' or 
the special control codes above X'F8'. Any 
value outside these ranges causes an error. 

Exit Conditions 

NZ = Error (invalid character sent) 

A = error code 


♦MODULO - A cyclical counting system, in which number1 
modulo number2 is the integral remainder after division of 
number1 by number2 . For example: 35 modulo 24 = 11. 
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TRS-80 


VDINIT Function Code 7 

Video Initialization 

Blanks the screen and resets the cursor to the upper left 
corner (Position 0 in the scroll mode illustration at the 
beginning of this section). Call VDINIT once before 
starting any I/O to the display. 

Entry Conditions 
A =7 

B = character size switch 

B = 0: 40 characters per line 

B / 0: 80 characters per line 

C = normal/reverse switch 

C = 0: reverse mode 
C / 0: normal mode 

Exit Conditions 

NZ = Error 

A = error code 
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VDLINE 
Video Line 


Function Code 9 


Writes a buffer of data to the display, starting at the 
current cursor position. The buffer should contain ASCII 
codes in the range [J0,127]. 


Control codes that are greater than than X* 20' are ignored. 
(For more information, see VDCHAR.) 


VDLINE is a scroll mode routine. 


Entry Conditions 
A =9 

(HL) = beginning of the text buffer 
B = number of characters to be sent 
C = end-of-line character 

This character is sent to the display after the 
buffer text. 

Exit Conditions 

NZ = Error 

A = error code 

In case of an error: 

B = number of characters not displayed ,including 
the one causing the error 
C = character causing the error 

Upon return, the cursor is set automatically to the position 
following the last character displayed. 
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TRS-80 


VDREAD Function Code 11 

Video Read 

Reads characters from the display into the buffer you 
specify. It is a graphics mode routine; when it reads past 
the last column, it wraps back to Column 0 on the next row. 
When it reads past Column 79 on Row 23, it wraps back to 
Column 0, Row 0. 

TRSDOS-II reads reverse (black on green/white) mode 
characters in ASCII codes, just as it does their normal 
counterparts. Reverse mode is indicated when the most 
significant bit (bit 7) is set. 

VDREAD can also be used to locate the cursor (see below). 

Entry Conditions 
A =11 

B = row on screen where the read starts , B < 24 

If B > 23, use B modulo 24 as the row position. 

C = column on screen where the read starts 

In the 80 characters-per-line mode, C < 80. For 
C > 79, use C modulo 80 as the column position. 
In the 40 characters-per-line mode, C < 40. For 
C > 39, use C modulo 40 as the column position. 

D = buffer length (in range [0,255]) 

D = 0: return the cursor position 
D / 0: read the display (B = row, C = column) 
(HL) = address of the text buffer 

Exit Conditions 

BC = current cursor position (B = row, C = column) 

The cursor position at exit is the same as at 
entry; VDREAD doesn't change it. 

NZ = Error 

A = error code 
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VIDKEY Function Code 12 

Combines VDLINE and KBLINE 

Sends a prompting message to the display and then waits for 
a line from the keyboard. VIDKEY is a scroll mode routine 
which combines the functions of VDLINE and KBLINE. 

Starting at the current cursor position, it displays the 

text buffer you specify. The buffer must contain codes 

less than X'80'. (See the VDLINE SVC for a list of received 
control codes and other details.) 

Once the text message is displayed, TRSDOS-II positions the 
cursor immediately after the last character displayed. (To 
move it to another position, you must place a control code 
at the end of the text buffer.) 

VIDKEY then uses KBLINE to get a line from the keyboard. 

(See the KBLINE SVC for a list of received control codes and 

other details.) 

Entry Conditions 
A =12 

B = number of characters to be displayed (in the 
range [ J0, 255 ]) 

C = length of the keyboard input field (in the 
range [ J0, 255 3 ) 

(HL) = beginning of the text buffer containing 
the display message 

(DE) = beginning of the text buffer where the 
keyboard input is to be stored 

Exit Conditions 

NZ = Error 

A = error code 

If Z is set (no error): 

B = number of characters input from keyboard , 
including carriage return, if any 
C = keyboard line terminator 

C = J0: input buffer was filled 
C / J0: C contains the control character that 
ended the line (carriage return) 
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If Z is not 
B 

C 


TRS-80 


set (error): 

number of characters not displayed , 

the one causing the error 

character causing the error 


including 
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VIDRAM 


Transfer Video Display to RAM or Vice-Versa 


Function Code 94 


Copies a screenful of graphics and/or text from a RAM buffer 
to the video display, or vice-versa. The programmer must be 
aware of the current display mode — 80 characters per line 
or 40 characters per line. 


Every possible data byte is treated as a displayable 
character. There are no cursor position or other control 
codes. The following table summarizes the character/code 
relationships for this routine: 


Hex Code Display Character 


00-1F Normal Graphics 

20-7F Normal ASCII Text 

80-9F Reversed Graphics 

A0-FF Reversed ASCII Text 

Entry Conditions 
A =94 

B = function code 

B = 0: copy from RAM to video 
B / 0: copy from video to RAM 
(HL) = RAM buffer The start of the buffer must be 

above X'2800'; the end must be below X'F000'. 
If the video is in the 80 characters-per-line 
mode, the buffer must be 80 * 24 = 1920 bytes 
long. 

If the video is in the 40 characters-per-line 
mode, the buffer must be 40 * 24 = 960 bytes 
long. 

Exit Conditions 
None 

(VIDRAM does not change the cursor position.) 
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WILD 

Wildcard Parser 


Function Code 51 


Compares a filespec with a wildcard spec, depending upon the 
contents of B, the function code entry condition. 

A mask is a filespec with asterisk(s) inserted in one or 
more positions in the name or extension. An asterisk means 
"one or more characters — don't care what they are." For 
example: 

. */BAS masks all files except those that have the 
extension /BAS. 

. *LST masks all files except those that have a 
filename ending in LST and no extension. 


The filespec is a standard TRSDOS-II filespec, terminated 
by a carriage return. 

For details on wildcard specs, see "Wildcard" in the 
"Introduction." 


Contents 

of B Result 


0 Sets the wildcard mask 

1 Compares the filespec with the mask 

2 Combines a separate name and 
extension into a filespec 

Note: Calling any other TRSDOS-II SVC may clear the mask. 

Therefore, you should use this procedure: 

1. Get the filespec(s) to be checked. 

2. Set the mask by calling WILD with B = 0. 

3. Compare the filespec with the mask by calling WILD 
with B = 1. 

4. Repeat Step 3 until all filespecs have been 
checked. 

5. Each time you call another TRSDOS-II SVC, you may 
have to reset the mask. 
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Entry Conditions 


A 

B 


51 

function switch 


B 

= 0: 

set the 

B 

= 1: 

compare 

B 

= 2: 

combine 


If B = 0: 

(HL) = wildcard mask 

If B = 1: 

(HL) = filespec 


If B = 2: 

(HL) = 11-byte buffer 

Bytes 0-7 = filename ; bytes 8-10 = extension 
You must justify both fields on the left, leaving 
trailing spaces as needed to fill the field. The 
format is: 


|N|A|M|E|0|)rf|tf|j*|E|x|T| 


The symbol 0 represents a blank space. 

(DE) = 13-byte destination buffer 

This buffer is to hold the compressed filespec 
contained in (HL). 


Exit Conditions 
If B = 0: 

NZ = Invalid mask specification 
If B = 1: 

NZ = File does not match or you have set no mask 
If B = 2: 

(DE) = 13-byte buffer containing filespec 

The filespec is created from the 11-byte source 
text. 
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TRS 


80 



WRITNX 


Function Code 43 


Write Next Record 

Writes the record following the last record accessed. If 
WRITNX is the first access after the file is opened, 
TRSDOS-II writes the first record. 

Before calling WRITNX, put your record in the record area 
pointed to by RECADR in the parameter list. Or, if the 
record length is 256 and the record type is fixed, your 
record is in the area pointed to by BUFADR. 

Entry Conditions 
A =43 

(DE) = data control block for the currently open file 
HL = Reserved for use in later versions of TRSDOS-II 

Exit Conditions 

NZ = Error 

A = error code 
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